Errors & retries
Diagnose failed requests and retry without duplicating work or losing a draft.
Error format
API failures return an HTTP status and an error object with code and message. Use code for application decisions and message for a readable explanation. Responses also carry a safe X-Request-ID for support.
Example error response
{
"error": {
"code": "authentication_required",
"message": "Use a valid workspace API key."
}
}Common HTTP statuses
| Status | What to check |
|---|---|
| 400 | Fix malformed JSON, unsupported fields, filters, or invalid parameters. |
| 401 | Restore a browser session or use a valid API key for the route. |
| 402 | Dataset/evaluation confirmation exceeds available service credits; training reports insufficient_credits as 409. |
| 403 | Check key scope, session-only requirements, product access, or XSRF state. |
| 404 | Check the route and owned resource identity. |
| 409 | Re-read the resource or order; its revision, state, source supply, or request key may conflict. |
| 410 | Dataset/evaluation quote expired; review a new quote. Training uses 409 training_quote_changed. |
| 422 | The selected model or configuration cannot satisfy the request. |
| 428 | Reload the saved resource and supply its current X-Resource-Revision. |
| 429 | Respect Retry-After when supplied and wait before retrying. |
| 503 | A required source, runtime, storage service, or pricing input is unavailable. |
Capacity and queueing
Every running batch needs GPUs that verify its model’s outputs, and those are limited. A batch starts at once when its model is already being served for another order, or when capacity for a new model is free; otherwise it waits in a single first-in, first-out line shared by batches, dataset orders and evaluations. An order on a model that is already running never waits for that line: it starts without taking a place. Capacity also has a daily limit, which resets at midnight UTC: an order is counted at its expected run time (eta_hours on the quote), and an order the day cannot take does not hold up smaller orders behind it that fit. An order too large for any single day starts as soon as some of the day’s capacity is left.
Placing an order is always allowed: a batch that cannot start yet stays validating (order status queued) with its price reserved. A batch that has not started 24 hours after it was queued ends failed with queue_timeout and is released in full; nothing is charged. A batch whose completion window passes before it starts ends expired, also released in full. Cancelling a waiting batch releases it in full.
Check before you order: GET /api/v1/capacity (public) gives the state for a new model, and every quote (POST /api/v1/dataset-orders/quotes) carries a capacity object for its model, which tells whether that model starts now. While a batch waits, the batch object carries reliquary_queue and the native order carries queue_position and estimated_start_at, with the reason in status_reason. These fields disappear once it starts.
estimated_start_at is an estimate, not a commitment: when waiting for capacity, the expected end of the running order that should free a place first (from its quoted time; null when there is nothing to base it on); when the daily capacity is reached, the next midnight UTC. Orders ahead of yours, cancellations and slower runs move it.
GET /api/v1/capacity
{
"state": "queued",
"queued_orders": 2,
"running_orders": 3,
"estimated_start_at": "2026-11-09T15:20:00.000Z",
"daily_capacity_resets_at": null,
"observed_at": "2026-11-09T13:02:11.000Z"
}| Field | Meaning |
|---|---|
| capacity.starts (quote) | now: an order placed now starts at once. queued: it would wait, with reason, queue_position, estimated_start_at and, for the daily limit, resets_at. |
| reason, status_reason | waiting_for_capacity: every place for a new model is taken; it starts when one frees, in line order. daily_capacity_reached: today’s capacity is used; it starts after resets_at (midnight UTC). |
| queue_position | The place in line among orders that have not started, counting from 1 (the quote shows the place a new order would take). |
| estimated_start_at | ISO 8601 estimate of the start, or null when unknown. |
| Qualification | An order that is qualified first waits in the same line for its qualification; its qualification time limit starts once it leaves the line. |
| reliquary_queue | On a validating batch: {queue_position, estimated_start_at, reason}. Not an OpenAI field: the OpenAI SDKs keep it as an extra field and parse the batch as usual. |
Retry the same action safely
- Retry read requests after transient network or service failures with bounded backoff.
- For an ambiguous creation result, preserve the original Idempotency-Key and identical body.
- After a known successful creation, read the returned resource rather than resubmitting it.
- An idempotency_conflict requires reconciliation; a new key is not a safe way to ignore the conflict.
- A quote_expired response requires a newly reviewed quote before confirmation.
Resolve a draft revision conflict
Updates and archival of saved resources use X-Resource-Revision with the resource’s current numeric revision. When the revision no longer matches, reload the resource and review the saved values before applying your changes.
The preferred resource revision header is X-Resource-Revision; the handler also accepts If-Match. Resource revisions, quote IDs, and idempotency keys each serve a different purpose. Jobs use decimal-string revisions and training launch uses a body revision; follow the relevant reference.
Send useful support context
Keep the request time, API path, HTTP status, error code, and X-Request-ID. Describe what you expected and whether the original action may have succeeded. Remove credentials and private file contents before sharing request details.
Support — Find the current support path.
Troubleshooting — Resolve common workspace issues.