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

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.

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.