Errors and retries
Check the HTTP status, diagnostic body, and execution summary before using a result or retrying. A request error and a partial execution need different handling.
On this page
Read the error body#
Generated source REST endpoints return failures under detail. Its value can be a string, a structured object, or an array of validation issues. For example:
{
"detail": {
"code": "builder_definition_version_conflict"
}
}
Structured execution errors can include message, classification, retryable, traceId, and retryAfterSeconds. Preserve the useful diagnostic fields without logging credentials or entire request headers. Other product endpoints can use different envelopes.
How long to wait#
When a response asks you to wait, read the HTTP Retry-After header, in seconds. The header has the same name on every route; the body can repeat the wait under different names: retryAfterSeconds in a source execution error, retry_after_seconds in an engine_request_limited error, and error.retry_after in a failed run object. Use them only when the header is missing.
Respond to the status#
| Status | Action |
|---|---|
202 |
Not an error: the run continues. Read GET /v1/runs/{run_id}/result after Retry-After seconds; do not resend the POST. |
400, 415, 422 |
Check JSON, content type, required headers, field types, and accepted inputs. Correct the request before resubmitting. |
401 |
Check the bearer key, expiry, and revocation state. Restore authentication. |
402 |
Check the workspace's spendable Units and the error details. Preserve the original request identity. |
403 |
Check key scopes, selected API access, and workspace membership. Repeating the request does not grant access. |
404 |
Check the source or run identifier and access to that resource. |
408, 413 |
Check request body timing or size. Keep the body within the contract's limits. |
409 |
Inspect the conflict code below. A version or delivery identity conflict requires a different response. |
429 |
Wait for Retry-After and reduce request frequency. engine_request_limited means a request limit was reached and the request was refused before it ran. A source run waiting for capacity is queued, not rejected. Preserve any existing run identity. |
500, 502, 503, 504 |
Preserve diagnostics. Check the run's recorded state before attempting recovery. Respect any retry delay. |
| Connection timeout or disconnect | The outcome is unknown. Keep the original request and idempotency key; recover the existing run. |
Recover an uncertain execution#
For customer source runs, a repeated request with the same Idempotency-Key, source, resolved version, input, and run options returns the same run: 202 while it runs, its final body once it ended, or its saved error. A different key starts a separate run. A failed run is never silently restarted.
If you know the run identifier, read GET /v1/runs/{run_id}/result with a key with run or results scope. Otherwise, follow idempotency and recovery before resubmitting.
Retry read-only status requests with bounded backoff when appropriate. Do not transfer the source-run replay rules to build submission, key creation, or payment operations; follow each operation's contract.
HTTP 200 can contain partial output#
Require summary.within_scope_passed: true and summary.status of completed or bounded. Check that summary.definition_version and metadata.definition_version match the requested version. Review missing fields and collection or detail limits before downstream use.
A bounded result can pass while leaving later source records uncollected. A partial response may still contain useful records, but it needs a deliberate decision before ingestion. See pagination and output.
Usage and billing review#
A delivered customer result includes delivery.runId, delivery.chargeReceiptId, and delivery.recordCount. Keep delivery.runId with the saved request; chargeReceiptId is the same identifier, because a run's Units are charged per committed page and recorded under the run (run.units_charged). Credit purchases and invoices have separate receipts.
Check workspace usage and payment records when reviewing a charge. For failed, repeated, or partial work, request a review instead of assuming a charge or refund outcome. See pricing, refunds and billing review, or contact support. Include run and receipt references, never API keys or payment-card details.
Error code reference#
The codes you are most likely to see, with what each one means and how to recover.
| Code | Meaning and recovery |
|---|---|
idempotency_key_required |
Missing or invalid Idempotency-Key. Supply the saved key for this intended execution. |
builder_definition_version_invalid |
Supply the full 64-character lowercase definition version. |
builder_definition_version_conflict |
The active definition differs from expected_version. Review the active contract before adopting it. |
builder_definition_version_selection_conflict |
Both version selectors were supplied. Use either expected_version or definition_version. |
builder_definition_version_not_accepted |
The requested immutable revision is not eligible for execution. Use an accepted revision. |
run_option_invalid |
422. max_items, timeout_seconds, or wait_seconds is outside its range; the error names the option, minimum and maximum. |
run_fields_invalid, run_fields_unknown, run_fields_unsupported |
422. fields is not a non-empty list of unique names, names a field the contract does not publish, or this API does not support field selection. |
run_nulls_invalid |
422. nulls is not a boolean, or ?nulls= is not true or false. |
run_items_query_invalid, run_list_query_invalid |
422. Unknown or malformed query parameters on /items or GET /v1/runs. |
delivery_identity_conflict |
The key was already bound to a different source, version, input, selected fields, or run options. Recover the original request or use a new key for a deliberately new execution. |
result_not_available, result_not_complete, result_not_running |
409 with Retry-After, from older result reads. Current run routes answer 202 with the run object while it continues. Treat either as not ready yet and read again with the same Idempotency-Key. |
result_integrity_failed |
409. The saved result failed its integrity check and was not returned. Contact support with the run. |
insufficient_units |
402. The workspace cannot cover the run. Review balance and the recorded run before recovery. |
usage_budget_exceeded |
409. The workspace's monthly usage budget cannot cover the request. Ask the Owner to review Billing. |
workspace_billing_identity_invalid |
403. The credential is not tied to a valid workspace billing identity. Use a workspace API key. |
legacy_credential_retired_for_execution |
403. A legacy credential can no longer run requests. Create an API key with the run scope. |
engine_request_limited |
429. A request limit was reached, so nothing ran. detail has code, message and, when known, retry_after_seconds. Wait for Retry-After, then send the same request with the same key. |
runs_unavailable |
503. Run storage did not answer. Retry shortly with the same key. |
builder_billing_unavailable |
Delivery cannot complete safely. Preserve the request and seek recovery without creating duplicate work. |
Unknown codes are non-success. Keep them for diagnosis rather than converting the response into an empty dataset.