Stable identifiers, actionable responses
Non-success responses use a JSON detail object with a stable error identifier and, where useful, limits or contextual fields. Use the HTTP status for broad handling and the identifier for precise recovery.
JSON
{
"detail": {
"error": "insufficient_credits",
"available": 82,
"reserved": 7
}
}Common errors
StatusIdentifierWhat to do
400invalid_requestThe request could not be accepted. Inspect detail and correct the payload.401missing_authenticationSend X-API-Key or an API-key Bearer token.401invalid_api_keyCreate a new key or confirm that the workspace key was not revoked.402insufficient_creditsAdd credits or reduce the requested targets and result limit.404job_not_found / batch_not_foundConfirm that the ID belongs to the authenticated workspace.409idempotency_key_conflictDo not reuse one idempotency key for a different payload.409results_not_readyPoll until the job or batch reaches a terminal state before exporting.422unsupported_operationRead GET /v1/platforms and select an enabled platform operation.422duplicate_batch_targetRemove duplicate targets from the batch.429rate_limit_exceededWait for Retry-After, then retry with the same idempotency key.429concurrent_job_limit_exceededWait for active work to finish before creating more jobs.503rate_limiter_unavailableRetry with backoff and preserve the original idempotency key.Retry policy
Retry connection failures, 429, and temporary 503 responses with exponential backoff and jitter. Preserve the exact payload and original idempotency key. Do not retry validation errors until the request changes.