A request to GET /api/v2/workflow/{id} can return 404 with {"message": "Workflow not found."} when it is sent within a few seconds of the workflow being created. The workflow exists, and it becomes readable shortly afterward. Retry the request with a short exponential backoff instead of treating the first 404 as final.
This applies to CircleCI cloud. The same short delay can affect other read endpoints for a new workflow, such as GET /api/v2/workflow/{id}/job and GET /api/v2/pipeline/{pipeline_id}/workflow.
Why it happens
Creating a workflow and making it readable through the API are two separate steps. A short delay exists between them, and a request that arrives inside that delay gets a 404 even though the workflow is real. The delay is usually well under a couple of seconds and occasionally a few seconds. It is not a guaranteed upper bound.
This is easiest to hit when something notifies your system the moment a workflow is created, and your system then looks the workflow up immediately. A GitHub commit status that CircleCI posts for a new workflow is one example. The status can reach your system before the workflow is readable through the API.
What to do
Retry the request when it returns 404 for a workflow that is known to exist, for example a workflow ID taken from a commit status target_url or from the response to a pipeline trigger. Use a short exponential backoff of about 1, 2, 4, and 8 seconds, which covers roughly 10 to 15 seconds in total. Stop after the last attempt so a real error still surfaces.
for delay in 1 2 4 8; do status=$(curl -s -o response.json -w "%{http_code}" \ -H "Circle-Token: $CIRCLE_TOKEN" \ "https://circleci.com/api/v2/workflow/$WORKFLOW_ID") [ "$status" != "404" ] && break sleep "$delay" doneApply the same retry to each lookup in the chain. If a request for a pipeline or its workflows follows the workflow lookup, a 404 on that later request can come from the same delay.
When a retry is not the answer
The API returns the same 404 for a workflow that is not readable yet and for a workflow that cannot be found at all. The response does not say which one it is. A 404 that continues after the retry window usually has another cause, such as:
A workflow ID that is incorrect or truncated.
An API token that is invalid, or a token for a user who does not have access to the project.
A project API token used with API v2, which does not support project tokens.
See CircleCI API v2 Returns "404 Not Found" for these checks. Only retry for workflows that are known to exist, so that a wrong ID or a missing permission does not wait through the whole backoff.