Errors

Errors use a stable JSON envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed."
  }
}

Common public status codes:

400 bad request, such as an invalid cursor
401 missing or invalid API key
402 billing disabled for the account
403 valid key without the required scope
404 job not found
409 idempotency conflict or invalid cancellation state
422 request validation failed
429 request exceeded an operational rate limit

Authentication failure:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

Scope failure:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not have the required scope."
  }
}

Billing disabled:

{
  "error": {
    "code": "billing_disabled",
    "message": "Billing is disabled for this account."
  }
}

Rate limited:

{
  "error": {
    "code": "rate_limited",
    "message": "The request exceeded the rate limit."
  }
}

Idempotency conflict:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The idempotency key was already used for a different score request."
  }
}

Do not parse messages for control flow. Branch on HTTP status and error.code.