# 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.

## 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
{
  "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](/docs/idempotency/) 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](/docs/pagination/).

## 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](/pricing/), [refunds and billing review](/legal/refunds/), or [contact support](/contact/). Include run and receipt references, never API keys or payment-card details.