Errors
HTTP status codes and response shapes.
Response Shape
Most application errors return a JSON object with a detail field:
{
"detail": "function not found"
}Validation errors return FastAPI's validation detail array:
{
"detail": [
{
"loc": ["body", "name"],
"msg": "Field required",
"type": "missing"
}
]
}Status Codes
| Status | Common cause |
|---|---|
401 | Missing bearer token, expired user session, invalid API key, or disabled API key. |
402 | Workspace compute credits are exhausted, so the run cannot reserve credits. |
403 | The caller lacks the required permission, the profile has not been invited, or the principal cannot access the target environment. |
404 | Project, function, workflow, version, or run was not found in the current workspace. |
409 | Attempted to trigger a target with no runnable current version or a disabled current version. Also: a DELETE was refused because the target still holds contents (a project with functions or runs, a function with endpoints) — pass force=true to delete them along with it, or a bucket delete was refused because the bucket is non-empty or still attached to a function. Also: a deploy or run violates the workspace compute policy, or the project or function is paused. |
422 | Invalid UUID, invalid query parameter, unknown JSON field, or invalid request body. |
500 | Unexpected infrastructure or database failure. |
502 | An upstream dependency failed. On a DELETE, this means releasing the target's Cloud Run or Prefect resources failed — nothing was deleted, and re-running the delete retries the teardown. At schedule sync it means a workflow's secret reference could not be read. |
Trigger Failures
SDK calls such as function.spawn(...), function.remote(...), workflow.spawn(...), and workflow.remote(...) create runs.
If submission to the execution infrastructure fails after the run row is created, the run is returned with:
{
"status": "failed",
"error": "Cloud Run submit failed: ..."
}Treat run status as the source of truth for execution outcome.
Reconciled Runs
There is a second, later way a workflow run (Prefect-backed) reaches failed: losing its
execution worker. If the run is still non-terminal more than 10 minutes after it started
and the execution infrastructure no longer knows its flow, the platform marks it failed the next
time it is read, with an event at stage reconcile and an error of the form:
{
"status": "failed",
"error": "run lost its execution worker (...)"
}This is why a run can appear stuck as running and then flip to failed when you poll
it: the failure is recorded lazily, on read, once the worker has been gone long enough
to rule out a slow start. Reconciliation also releases the credits the run was holding.