application/problem+json with a stable code, a title, a human detail, retryable and request_id (also the X-Request-Id header). x-should-retry mirrors retryable, and Retry-After gives the wait when there is one. A run that starts and then fails is not an HTTP error: the run object answers 200 with status: "failed" and an error with one of the run codes below.
Request errors
Run errors
A run’s own
error is not the only place OUTPUT_UNAVAILABLE appears. One output of a run can carry error: {code: "OUTPUT_UNAVAILABLE"} while the others are delivered. With a key in the customer price view it can also appear on an output of a completed run that was charged: a stored output that states the provider’s bill and has no copy without it is listed without its link. Read that output with a standard key.
Retry guidance
- Retry automatically only on network errors and timeouts (same
Idempotency-Key) and on the codes below.retryableandx-should-retryon the answer always win over this table (for exampleRATE_LIMITEDis not retryable once thedaypolicy is exhausted). Every other code needs a change before the request is sent again.
- Backoff: capped exponential with full jitter,
sleep = random(0, min(30 s, 1 s × 2^attempt)), at most 4 retries and about 2 minutes in total for a create. Exception (rule 5, ADR 0167): a create whose outcome is still unknown after those retries may be sent again with the same key at most 3 more times, each at least 60 s after the last (up to 8 sends in about 4 minutes); a keyed replay is answered before the input checks, so these resolve in milliseconds once the run exists. - Retry-After is a floor: wait at least that long (add 0–20 % jitter). Spiral never sends more than 60 s.
- Keys: send a UUIDv4
Idempotency-Keyon everyPOST /v1/runsand store it with your task before sending. Reuse it for every retry of the same intent, including after a restart; a replay returns the original run withIdempotent-Replayed: true, never a second run or charge. Use a new key only to start a new run deliberately. A key replays its run for 24 hours; after that the same key starts a new run. - Unknown outcome of a create (timeout, connection reset): retry with the same key. Never switch to a new key until the first request is known not to have created a run.
- Failed runs: start at most one new run (new key), and only when
error.retryableis true.PROVIDER_OUTCOME_UNKNOWNis not retryable: check your own results first, because the provider may have done the work. - Polling: prefer webhooks. Otherwise use
GET /v1/runs/{id}?wait_seconds=30, or poll byRetry-Afteron 202 and running responses; without it start at 1 s (search and scrape), 2 s (images), 5 s (video and audio), back off × 1.5 up to 30 s, and stop at a final status. Polling has its own rate-limit policy (poll), so it never consumes create quota. - Webhooks: verify the signature over the raw body with your org’s signing secret (any Standard Webhooks library; during a secret rotation the header carries two signatures and either verifies); answer 2xx fast and do the work afterwards (a delivery that takes over 10 s is re-sent); ignore event types you do not handle (types are added over time); dedupe on
webhook-idfor at least 7 days (every re-send carries the same one); ontruncated: trueread the run withGET /v1/runs/{id}(the body left outoutputto stay under receiver limits); ignore a delivery whose runsequenceis lower than one already applied; download outputs within 7 days. A webhook is sent right after the run is charged, so it usually carries the final charge (sequence4); when the provider’s bill comes later it carriescost.state: held(sequence3) and the final charge is onGET /v1/runs/{id}(sequence4). No separate billing event is sent. - Runs cannot be canceled after submission. Poll the run or wait for its configured terminal webhook.