# 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 request_id field. Example pattern: type error, error type not_found_error with its message, request_id 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 _request_id property, C#, Go, Java, and PHP through raw-response accessors, Ruby through middleware. Use with_raw_response (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.