Error Handling

Why Error Handling Matters

Most API documentation lists error codes. This guide goes further — every error below was deliberately triggered against the live Claude API. The exact messages, the real responses, and the subtle behaviors that official documentation often misses. Building a reliable Claude integration means handling not just the errors that throw — but the ones that don’t.

The Error Response Structure

Every Claude API error follows the same JSON shape:

{
  "type": "error",
  "error": {
    "type": "error_type",
    "message": "Human readable description"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

This consistency is useful — one error handler covers all error types:

Field	Type	Description
`error.type`	string	Machine-readable identifier. Use in your error handling logic.
`error.message`	string	Human-readable explanation. Use for logging and debugging.
`request_id`	string	Unique request ID. Required when contacting Anthropic support.

Always log request_id on every failed request. If you need Anthropic support to investigate a specific error, this ID is the only way their team can trace it.

authentication_error — 401

What Causes It

An invalid or missing API key. The most common cause is an environment variable that was not set correctly or a key that was regenerated without updating all the places it is used.

Real Response

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

How to Fix

Confirm the x-api-key header is present on the request
Verify the key starts with sk-ant-
Check that your environment variable is set and the correct environment is active in your API client
If you recently regenerated the key, update it everywhere it is referenced

Never hardcode your API key in source code or commit it to version control. Store it as an environment variable and reference it server-side only. If a key is ever exposed, revoke it immediately from the Anthropic Console and generate a new one.

invalid_request_error — 400

What Causes It

A malformed request — missing required fields, invalid values, or incorrect structure. This is the broadest error type and covers several distinct problems. Always read error.message to understand exactly what is wrong.

Real Responses

Missing messages field:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: Field required"
  },
  "request_id": "req_011CdDNvMxUSR7s5EhvS5VaC"
}

Missing anthropic-version header:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-version: header is required"
  },
  "request_id": "req_011CdDPQakwLLcrS9PCkS5dL"
}

How to Fix

Confirm every required field and header is present: Required fields:

Field	Type	Requirement
`model`	string	Must be a valid model string
`max_tokens`	integer	Must be greater than `0`
`messages`	array	Must contain at least one user message

Required headers:

Header	Value
`x-api-key`	Your API key
`anthropic-version`	`2023-06-01`
`content-type`	`application/json`

A 400 covers many different problems. Unlike 401 and 429 which are specific, a 400 can mean missing fields, invalid values, malformed JSON, or incorrect message structure. Always read error.message first before debugging further.

not_found_error — 404

What Causes It

A model string that does not exist. This error is distinct from invalid_request_error — the request was structurally valid, but the resource it referenced does not exist.

Real Response

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: claude-fake-model"
  },
  "request_id": "req_011CdDP9LQZyMSdCgGCAizhs"
}

How to Fix

Use a valid model string:

Model	String
Claude Sonnet	`claude-sonnet-4-6`
Claude Opus	`claude-opus-4-6`
Claude Haiku	`claude-haiku-4-5`

Most community API references document only authentication_error and invalid_request_error. The not_found_error type was discovered through real testing — by deliberately passing a model string that does not exist. It is a distinct error type worth handling separately in your application logic.

rate_limit_error — 429

What Causes It

Too many requests sent in a short period. Anthropic applies rate limits per API key based on your usage tier.

Response

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please retry after a short delay."
  }
}

How to Fix

Implement exponential backoff — wait before retrying and increase the wait time on each subsequent failure:

Attempt 1 fails → wait 1 second → retry
Attempt 2 fails → wait 2 seconds → retry
Attempt 3 fails → wait 4 seconds → retry
Attempt 4 fails → wait 8 seconds → retry

Most rate limit errors resolve within one or two retries. If you consistently hit rate limits, review your request volume or contact Anthropic about upgrading your usage tier.

Silent Truncation — 200

What Makes This Different

This is not an error response. It is a 200 OK. And it is the most dangerous failure mode in the Claude API.

What Causes It

Setting max_tokens too low to generate any output. The API accepts the request, starts generating, immediately hits the token limit, and returns an empty response — with no error thrown.

Real Response

{
  "model": "claude-sonnet-4-6",
  "type": "message",
  "role": "assistant",
  "content": [],
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 8,
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

content is an empty array. output_tokens is 0. stop_reason is "max_tokens". HTTP status is 200 OK.

This is the hardest failure to catch because it looks like success. An application that does not check stop_reason will pass an empty response to the user — a blank screen with no explanation. This was discovered by deliberately setting max_tokens: 0 during testing. Always check stop_reason before processing any response.

How to Fix

Always check stop_reason before processing Claude’s output:

const response = await callClaude(request);

if (response.stop_reason === "max_tokens") {
  // Response is incomplete — handle truncation
  console.warn("Response truncated. Increase max_tokens.");
}

if (response.stop_reason === "end_turn") {
  // Response is complete — safe to process
  const text = response.content[0].text;
}

Complete Error Reference

Error Type	HTTP Status	Cause	Fix
`authentication_error`	401	Invalid or missing API key	Verify `x-api-key` header and environment variable
`invalid_request_error`	400	Missing required field	Ensure `model`, `max_tokens`, and `messages` are present
`invalid_request_error`	400	Missing version header	Always include `anthropic-version: 2023-06-01`
`not_found_error`	404	Model string does not exist	Use a valid model string
`rate_limit_error`	429	Too many requests	Implement exponential backoff and retry
Silent truncation	200	`max_tokens` too low	Check `stop_reason` before processing any response

A Single Error Handler

Because all errors share the same structure, one function handles everything:

async function callClaude(requestBody) {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "x-api-key": process.env.ANTHROPIC_API_KEY,
      "anthropic-version": "2023-06-01",
      "content-type": "application/json"
    },
    body: JSON.stringify(requestBody)
  });

  const data = await response.json();

  // Handle explicit API errors
  if (data.type === "error") {
    console.error(`[${data.error.type}] ${data.error.message}`);
    console.error(`Request ID: ${data.request_id}`);

    switch (data.error.type) {
      case "authentication_error":
        throw new Error("Invalid API key. Check your environment variable.");
      case "invalid_request_error":
        throw new Error(`Bad request: ${data.error.message}`);
      case "not_found_error":
        throw new Error(`Resource not found: ${data.error.message}`);
      case "rate_limit_error":
        // Implement retry with backoff
        throw new Error("Rate limit hit. Retry with exponential backoff.");
      default:
        throw new Error(`API error: ${data.error.message}`);
    }
  }

  // Handle silent truncation
  if (data.stop_reason === "max_tokens") {
    console.warn("Response truncated — increase max_tokens for complete output.");
  }

  return data;
}

Errors During Streaming

Streaming responses can fail mid-stream. Anthropic sends an error event when this happens:

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

Your streaming implementation must handle the error event type — not just content_block_delta and message_stop:

For each incoming event:
"content_block_delta" → extract and display text
"message_stop" → close the stream
"error" → handle the error gracefully
"ping" → ignore

A stream that starts successfully can still fail partway through. Never assume a stream that opened will complete.

Error Handling API Reference

Interactive playground for testing error responses

Streaming

Handle errors that occur mid-stream

Tool Use

Handle tool use errors and failed tool calls

Tokens

How max_tokens affects response completeness and silent truncation

Getting Started

Core Concepts

Guides

Why Error Handling Matters

The Error Response Structure

authentication_error — 401

What Causes It

Real Response

How to Fix

invalid_request_error — 400

What Causes It

Real Responses

How to Fix

not_found_error — 404

What Causes It

Real Response

How to Fix

rate_limit_error — 429

What Causes It

Response

How to Fix

Silent Truncation — 200

What Makes This Different

What Causes It

Real Response

How to Fix

Complete Error Reference

A Single Error Handler

Errors During Streaming

Further Reading

Error Handling API Reference

Streaming

Tool Use

Tokens

​Why Error Handling Matters

​The Error Response Structure

​authentication_error — 401

​What Causes It

​Real Response

​How to Fix

​invalid_request_error — 400

​What Causes It

​Real Responses

​How to Fix

​not_found_error — 404

​What Causes It

​Real Response

​How to Fix

​rate_limit_error — 429

​What Causes It

​Response

​How to Fix

​Silent Truncation — 200

​What Makes This Different

​What Causes It

​Real Response

​How to Fix

​Complete Error Reference

​A Single Error Handler

​Errors During Streaming

​Further Reading

Error Handling API Reference

Streaming

Tool Use

Tokens

Why Error Handling Matters

The Error Response Structure

authentication_error — 401

What Causes It

Real Response

How to Fix

invalid_request_error — 400

What Causes It

Real Responses

How to Fix

not_found_error — 404

What Causes It

Real Response

How to Fix

rate_limit_error — 429

What Causes It

Response

How to Fix

Silent Truncation — 200

What Makes This Different

What Causes It

Real Response

How to Fix

Complete Error Reference

A Single Error Handler

Errors During Streaming

Further Reading