Send a Message
Endpoints
Error Handling
Understand every Claude API error type, what causes it, and exactly how to fix it.
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:- Confirm your
x-api-keyheader 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 readerror.message to understand exactly what is wrong.
Missing messages field:
- 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
messagescontains at least one user message - Confirm
max_tokensis an integer greater than0
not_found_error — 404
Triggered by: A model string that does not exist. Real response: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: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:
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.
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
Headers
Example:
"2023-06-01"
Body
application/json
Response
Successful response
Example:
"msg_01XFDUDYJgAACzvnptvVoYEL"
Example:
"message"
Example:
"assistant"
Example:
"claude-sonnet-4-6"
Available options:
end_turn, max_tokens, stop_sequence, tool_use Example:
"end_turn"