CleanedWeb
Markdown

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:

JSON · 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.

Updated Get help
Search across the documentation · Esc to close