Errors | CloudRaker documentation

Errors come back as JSON with a snake_case code and a matching HTTP status:

1 { "error": "invalid_status" }

Some errors carry extra detail alongside the code (for example a list of offending field keys). Always branch on the HTTP status first, then on the error code.

Status codes

Status	Meaning
`401`	Unauthenticated: missing, malformed, or invalid token
`402`	Out of credits. The organization’s balance is exhausted. Top up to resume work
`403`	Authenticated but lacks a write permission, or not an admin
`404`	Not found. Also used as a leak-guard for a missing `space:read` grant: it hides existence instead of a `403`
`409`	State conflict (for example, reprocessing a non-failed file, or deleting a definition that still has objects)
`410`	Expired but still within a grace window (see the Process API)
`413`	Payload too large (relayed from file storage)
`422`	Invalid body: an unknown or archived field, or a `$`-injection attempt
`429`	Too many requests. The organization’s rate limit is exhausted. Wait for `Retry-After`
`503`	A downstream dependency is unavailable, or auth validation hit a transient auth-service outage

The 404-as-leak-guard convention matters. A 404 on a space-scoped resource can mean “does not exist” or “you cannot see it.” The API deliberately does not distinguish the two. You cannot probe for resources you lack access to.

Common error codes

Code	Typical status	Meaning
`unauthorized`	401	Missing or malformed `Authorization` header
`invalid_token`	401	Token failed validation
`auth_unavailable`	503	Transient auth-service outage during key validation. Retry. Not a revoked key
`org not found`	404	Token has no associated organization
`invalid_request`	400	Malformed request (for example, combining `view` with `filter`/`sort`)
`invalid_status`	400	Unknown `status` value in a query filter
`view_not_found`	404	Unknown or wrong-scope saved view
`objects_exist`	409	Deleting an object definition that still has live objects
`payload_too_large`	413	Body exceeded the size limit
`not_found`	404	Unknown id (or hard-wiped resource)
`expired`	410	Purged resource, still in its grace window
`upstream_error`	5xx	A downstream worker returned an error

Errors on capability endpoints

The capability endpoints (/v1/…) use a richer envelope. The legacy { "error": … } shape above is unchanged on every other route.

1 {
2   "code": "invalid_request",
3   "message": "file: provide exactly one of `file` or `files`",
4   "retryable": false,
5   "requestId": "req_01KYCZWG1M7V8HM95NBV63PET2",
6   "docUrl": "https://docs.cloudraker.com/developers/errors#invalid_request"
7 }

Field	What it is
`code`	Stable machine-readable code. Branch on this.
`message`	Human-readable. Where a field is at fault, the field’s path prefixes the message. Never parse it.
`retryable`	Whether repeating the identical request could succeed.
`requestId`	Also returned as the `x-request-id` response header. Quote it in support requests.
`docUrl`	Present when a specific rule was broken. It links to the rule.

invalid_request

400. The body or query is malformed: a missing field, a bad type, or a mutually exclusive pair sent together (file and files, schema and action, spaceId and space on keep). It also covers a parameter that does not apply to the input, such as style on a PDF or mode on audio. It also covers a saved sign action passed as another verb’s action. message names the offending field. Fix the call. An identical retry fails identically.

A slow run is never an error. At the synchronous cap, the call returns 202 with the run handle. A run that waits on a human returns 202 with needs_input. Both are successes with a body to poll.

invalid_schema

400. The schema you sent to extract breaks the extraction schema dialect. docUrl points at the exact rule. message points at the exact node.

not_found

404. No such run, file, template, action, webhook endpoint, or produced output. The API also returns it when a sub-route addresses a step the run does not have, for example GET /v1/runs/plr_…/envelope on a pipeline with no sign step. Right after a synchronous run returns, GET /v1/runs/:id/output/:name can 404 for a moment while the produced file registers. Re-fetch the run and use output.file.url.

Other capability codes

Code	Status	Meaning
`unauthorized` / `invalid_token`	401	Missing, malformed, or invalid bearer token.
`credits_exhausted`	402	The organization is out of credits. Nothing was started and nothing was charged. Top up or upgrade the plan in Settings → Billing. Reads, `cancel`, `keep`, and deletes keep working meanwhile.
`rate_limited`	429	The organization’s rate limit is exhausted. Nothing was started. Wait for the `Retry-After` seconds and retry.
`run_expired`	410	The run passed its `ttl` and was purged. This is terminal. The result is gone. After the grace window, this becomes `404`.
`upstream_error`	4xx	Fallback code when a downstream stage rejects the request and has no more specific code. Fix the call. `retryable` is `false`.
`action_unknown`	4xx	The `action` you referenced does not exist in your organization, by id or by slug.
`file_ineligible`	4xx	The document cannot be an input: wrong type, or parsing never finished.
`file_not_ready`	409	The file exists, but upload or parsing is not complete. Poll `GET /v1/files/:id` until `ready`.
`output_not_ready`	409	A run’s output file is registered, but its bytes are still settling. Retryable. Wait a moment and re-request `output.file.url` or `/v1/runs/:id/output/:name`. It is never a `404`.
`file_fetch_failed`	422	The API could not fetch the `url` at registration time: unreachable host, non-2xx response, or an empty body.
`file_unreadable`	502	The source was reached, but its bytes could not be read.
`file_upload_failed`	502	The fetched bytes could not be stored. The usual cause is a source with no `Content-Length`. See Files.
`already_kept`	409	The run was already kept into a different space. A run belongs to one space.
`pipeline_running`	409	You tried to keep a run that has not finished. Wait for a terminal status.
`webhook_endpoint_not_found`	422	`webhook: {id}` references an endpoint that does not exist.
`webhook_endpoint_disabled`	422	The referenced endpoint is paused. Re-enable it with `PATCH /v1/webhooks/:id`, or send `webhook: {url}`.
`ambiguous_capability`	4xx	A saved `redact` action did not say whether it targets documents or audio. Send `mimeType` at creation.
`run_too_large`	4xx	The request exceeds the dispatch size budget. Send fewer files, or a smaller schema.
`schema_too_large`	4xx	The inline `schema` is over the 64 KB limit. See size limit.
`internal_error`	5xx	Something failed on our side. `retryable` is `true`. Back off and retry.

New codes can appear over time. Branch on the codes you handle. Treat an unknown code as a plain failure of its HTTP status class.

Retrying

503 auth_unavailable and 503 downstream errors are transient. Retry with exponential backoff.
410 expired is terminal for that resource. Do not retry.
429 rate_limited is also transient. Sleep for the Retry-After seconds, then back off exponentially. Rate limits covers the budget and the tactics.
402 credits_exhausted is not transient. A retry burns nothing, but it cannot succeed until you top up the balance.
4xx other than 429 means a bad request. Fix the call instead of retrying.

Where to go next

Runs

Statuses, expiry, and what a 410 run_expired means for your result.

Rate limits

The per-organization budget, the 429 envelope, and how to back off.

Pagination and filtering

How listing and querying work across the API.