Anthropic error shape and request_id: log the ID on every failure, it is your support ticket

TL;DR: Every Anthropic error is JSON with a top-level error object carrying type and message, plus a requestid. The same ID rides in the request-id response header. The error envelope: parse it once, log the ID always The documented shape: a top-level type of error, an error object with type and message, and a requestid field. Parse errors by the inner error type and the HTTP status, never by substring-matching the message.

The error envelope: parse it once, log the ID always

The documented shape: a top-level type of error, an error object with type and message, and a requestid field. Example pattern: type error, error type notfounderror with its message, requestid like req_011CSHoEeqs5C35K2UUqR7Fy.

What to do

1. Parse errors by the inner error type and the HTTP status, never by substring-matching the message. Per the versioning policy, type values can grow over time; code that switches on an exhaustive list of known types breaks when a new one appears. Branch on known types, default sensibly.
2. Log the request_id for every failed request. When you contact support, include it: it is the fastest path to a diagnosis.
3. Read the request-id header too. SDKs expose it on response objects: Python and TypeScript as a requestid property, C#, Go, Java, and PHP through raw-response accessors, Ruby through middleware. Use withrawresponse (or the Ruby middleware) for other headers like anthropic-organization-id.
4. On Claude Platform on AWS there are two request IDs: the AWS request ID (x-amzn-requestid, primary, indexed in CloudTrail) and the Anthropic request ID (request-id, secondary). Use the AWS one for CloudTrail lookups and the Anthropic one for Anthropic support tickets.

The trap

Exhaustive string matching on error types or messages. New types arrive under the versioning policy, and a default branch that treats unknown errors as fatal turns a new retryable error into an outage. The other trap: debugging a production failure with no request_id anywhere in your logs, which leaves support with nothing to look up.

Checklist

• Log status code, error type, and request_id on every API failure. Three fields, always.
• Unknown error type: fall back to status-class behavior (4xx fix, 429 back off, 5xx retry), do not crash.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Anthropic error shape and request_id.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Anthropic's error reference documents the error envelope (type, error type/message, request_id), the request-id header, per-SDK accessors, and the dual request IDs on Claude Platform on AWS. Verified live at https://platform.claude.com/docs/en/api/errors.