Errors

Every error uses the same JSON body. A failed request is never returned with HTTP 200. The two cases that put an error inside a 200 response are described in Errors inside a response.

{
  "error": {
    "message": "Model \"example/unknown\" was not found.",
    "type": "not_found_error",
    "code": "model_not_found",
    "param": "model",
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "doc_url": "https://example.com/docs/errors/#model_not_found"
  }
}

• message: a short explanation for people.
• type: the error category.
• code: a stable identifier for programs. Branch on code, not on message.
• param: the request parameter that caused the error, or null.
• request_id: the ID of the request. Keep it when you ask for support.
• doc_url: a link to the entry for this code on this page.
• details: optional machine-readable context. The fields depend on the error:
  • For a value that must come from a fixed set, details.allowed lists the accepted values.
  • For a number outside its range, details.minimum and details.maximum give the limits.
  • For a 402, details.limit_source is balance or key. The other fields give the amounts, and for a key limit also the period and details.resets_at. See Balance and key limits.
  • For a reference image URL that cannot be used, details.reason says why.
  • For a reference image sent as a data URI that is too large, details.max_bytes is the limit.
  • For payload_too_large, details.max_bytes is the limit.
  • When a request that waited for a job fails because the job failed, details.job_id is the ID of the job.
  • When a request depends on the status of a job, such as cancelling a job that has finished or downloading a video that has no file, details.status is the status of the job.

Two cases report an error inside a 200 response:

• A streamed chat response that fails after it has started. The error arrives as an event in the stream. See Chat.
• A job that failed. Reading the job returns 200, and the error field of the job has the same fields as an error response. See Jobs.

POST /v1/messages returns every error in the Anthropic shape: type is error, the error is in error, and request_id is a top-level field. The codes and the HTTP statuses are the same as in the table below. See Chat.

Each code links back to its row, so the anchor in doc_url (#<code>) opens the matching entry.