Errors

QCOS returns JSON errors with an HTTP status code and a human-readable detail.

{
  "detail": "Insufficient credits",
  "error_code": "INSUFFICIENT_CREDITS",
  "status_code": 402
}

Common status codes

Code	Meaning	Action
`400`	Invalid request	Fix payload shape (e.g. `cost_ceiling_not_evaluated_by_qcos`: `max_cost_usd` ceilings belong to the Platform, not QCOS — remove the field)
`401`	Missing or invalid API key	Check `Authorization`
`403`	Scope or license denied	Check plan, license, scope
`402`	Insufficient credits	Add credits or reduce workload
`404`	Resource not found	Check job id or path
`409`	Duplicate or conflicting job	Use idempotency keys
`422`	Validation error	Inspect field details
`429`	Rate limit exceeded	Backoff and retry
`503`	Backend unavailable	Retry or choose another backend

Retry 429, 500, 502, 503 and provider timeouts with exponential backoff.
Do not blindly retry paid QPU submissions without an Idempotency-Key.
For approval_required, call the approval flow or resubmit with explicit cost confirmation.