POST
Send a Message

Overview

Every error returned by the Claude API follows the same structure — one error handler covers all of them. Understanding what triggers each error and how to recover from it is essential for building reliable integrations.

Error Response Structure

All errors return the same JSON shape regardless of type:
Always log request_id on every failed request. If you need to contact Anthropic support about a specific error, this ID is what their team needs, to investigate.

Error Reference

Every error below was deliberately triggered and tested against the live API. The exact messages shown are real responses — not approximations.

authentication_error — 401

Triggered by: Invalid or missing API key. Real response:
How to fix:
  • Confirm your x-api-key header is present on every request
  • Verify the key starts with sk-ant-
  • Check that your environment variable is set correctly and the active environment is selected in your API client
  • If the key was recently regenerated, update it everywhere it is used

invalid_request_error — 400

Triggered by: Malformed request — missing required fields, invalid values, or incorrect structure. This is the most common error type and covers several different problems. Always read error.message to understand exactly what is wrong. Missing messages field:
Missing anthropic-version header:
How to fix:
  • Confirm all three required fields are present: model, max_tokens, messages
  • Confirm all three required headers are present: x-api-key, anthropic-version, content-type
  • Confirm messages contains at least one user message
  • Confirm max_tokens is an integer greater than 0

not_found_error — 404

Triggered by: A model string that does not exist. Real response:
How to fix: Use a valid model string:
not_found_error is distinct from invalid_request_error. A 404 means the request was structurally valid but referenced a resource that does not exist. A 400 means the request itself was malformed.

rate_limit_error — 429

Triggered by: Too many requests in a short period. Response:
How to fix: Implement exponential backoff — wait before retrying, and increase the wait time on each subsequent failure:
Most rate limit errors resolve within one or two retries.

Silent Truncation — 200

This is not an error response — but it is the most dangerous failure mode. Triggered by: max_tokens set too low to generate any output. Real response:
The API returns 200 OK with an empty content array and stop_reason: "max_tokens". No error is thrown. Your application receives a successful response with no text.
This is the hardest failure to catch because it looks like success. Developers who do not check stop_reason will display blank responses to users without knowing why. Always check stop_reason before processing Claude’s output — end_turn means complete, max_tokens means truncated.

Complete Error Reference Table

Building a Single Error Handler

All Claude API errors share the same structure — one handler covers everything:

Further Reading

Send a Message

Full endpoint reference including all error codes

Tokens

How max_tokens affects response completeness

Streaming

Handle errors that occur mid-stream

Tool Use

Handle tool use errors and failed tool calls

Authorizations

x-api-key
string
header
required

Headers

anthropic-version
string
required
Example:

"2023-06-01"

Body

application/json
model
enum<string>
required

The Claude model to use.

Available options:
claude-sonnet-4-6,
claude-opus-4-6,
claude-haiku-4-5
Example:

"claude-sonnet-4-6"

max_tokens
integer
required

Maximum number of output tokens to generate.

Required range: x >= 1
Example:

1024

messages
object[]
required

Response

Successful response

id
string
Example:

"msg_01XFDUDYJgAACzvnptvVoYEL"

type
string
Example:

"message"

role
string
Example:

"assistant"

content
object[]
model
string
Example:

"claude-sonnet-4-6"

stop_reason
enum<string>
Available options:
end_turn,
max_tokens,
stop_sequence,
tool_use
Example:

"end_turn"

stop_details
object | null
usage
object