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. Some failures also include an HTTP Retry-After header. Preserve the useful diagnostic fields without logging credentials or entire request headers. Other product endpoints can use different envelopes.

Respond to the status#

Status	Action
`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. A saved result may need settlement; preserve its 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, delivery identity, or pending result requires a different response.
`429`	Respect `Retry-After` when present and reduce request frequency or concurrency. Preserve any existing execution identity.
`500`, `502`, `503`, `504`	Preserve diagnostics. Check recorded execution 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 work.

Resolve common codes#

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.
`delivery_identity_conflict`	The key was already bound to a different source, version, input, or execution surface. Recover the original request or use a new key for a deliberately new execution.
`result_already_running_or_failed`	The request identity exists and cannot be automatically restarted. Inspect the run; honor `Retry-After`, but do not assume waiting will resolve a recorded failure.
`result_not_available`	The recorded result is not available for delivery. Inspect its state before collecting again.
`insufficient_units`	The workspace cannot cover the delivery. Review balance and saved execution state before recovery.
`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.

Recover an uncertain execution#

For customer source runs, a repeated request with the same Idempotency-Key, source, resolved version, endpoint, and input can return the retained delivery. A different key starts a separate execution. A run that is still running or recorded as failed is not silently restarted.

If you know the run identifier, retrieve the stored result with GET /v1/sources/{source_id}/runs/{run_id}/result and a key with 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 those references with the saved request. They identify the execution delivery; 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.