Claude Platform on AWS exposes the Claude API surface directly, so its error model is the first-party one — HTTP status codes with JSON error bodies — with a thin AWS-specific layer on top from the SigV4 gateway. Sorting errors into three buckets keeps handling simple: your request is wrong (4xx — fix it, don't retry), you're going too fast (429 — slow down and retry), and the service hiccupped (529/5xx — retry with backoff).
The setup-time errors worth memorizing
A few failures are specific to this platform's AWS front door and account for most first-week confusion:
"Outbound web identity federation is disabled for your account." The most common setup error. It means the one-time prerequisite — aws iam enable-outbound-web-identity-federation — was never run for the AWS account. Until it is, every request fails.
A generic signature-rejection error. The SigV4 signing region must match the region in the endpoint URL; a mismatch in either direction produces a generic rejection, not a specific diagnostic. If signatures suddenly fail after a config change, check region consistency first.
An error at client construction, before any request. AnthropicAWS deliberately raises if it cannot resolve an AWS region or a workspace ID — there are no default fallbacks. Set AWS_REGION and ANTHROPIC_AWS_WORKSPACE_ID.
403 Forbidden. The request reached the server and was refused: either the workspace_id is wrong, or the calling principal is missing the required IAM action (for example aws-external-anthropic:CreateInference for messages, or CallWithBearerToken when using API-key auth).
Runtime status codes
| Code | Meaning | Action |
|---|---|---|
| 400 | Invalid request — e.g. a prompt exceeding the context window ("prompt is too long"), inference_geo on a model older than Opus 4.6 / Sonnet 4.6, or a Fable 5 request from an org without 30-day retention | Fix the request; never retry as-is |
| 403 | Wrong workspace ID or missing IAM action | Fix config/policy |
| 429 | Rate limit exceeded (RPM or token-per-minute) | Honor retry-after, then retry |
| 529 | Service overloaded | Retry with backoff; reduce concurrency |
| 5xx | Transient server-side fault | Retry with backoff |
On 429s specifically: rate limits on this platform are managed by Anthropic (not AWS Service Quotas), enforced with a token-bucket algorithm, and the response includes a retry-after header telling you how long to wait. Persistent 429s at normal traffic mean you need a limit increase — new organizations start on the Start tier and do not move up automatically — which is a conversation with Anthropic, not a code change. A 529 is different in kind: it signals platform-wide pressure rather than your quota, so aggressive immediate retries make things worse. Back off and consider shedding low-priority load.
What the SDK does for you
The anthropic SDK retries transient failures — connection errors, 429s, and server-side faults — automatically with exponential backoff, and raises typed exceptions (RateLimitError, APIStatusError, and friends) when retries are exhausted. You can tune the retry count via the client's max_retries setting; check the SDK documentation for current defaults. Add your own layer only where the SDK can't see the whole picture:
Queue-level backoff when a burst of work would just re-trigger 429s — pace submissions rather than retrying each request harder. Idempotency guards where a retry could duplicate a side effect your code performs per response. Failover: Claude Platform on AWS uses a separate capacity pool from both the first-party API and Amazon Bedrock, and workloads can run on multiple platforms and fail over between them — a sustained-529 escape hatch that no per-request retry policy can offer.
x-amzn-requestid (indexed in CloudTrail; quote it to AWS support) and request-id (quote it to Anthropic support). An error report without them is a much slower support ticket.Where to go next
Rate-limit design lives in quota management; multi-platform failover in checking platform availability. For the audit trail behind those request IDs, see CloudTrail logging.