Anthropic HTTP headers — request and response
Status: DOCUMENTED; core request/response headers LIVE_VERIFIED 2026-09-18; x-should-retry, CF-RAY, usage.inference_geo value LIVE_DISCOVERED.
Sources: https://platform.claude.com/docs/en/api/overview (Authentication, Response headers) · https://platform.claude.com/docs/en/api/versioning · https://platform.claude.com/docs/en/api/beta-headers · https://platform.claude.com/docs/en/api/rate-limits#response-headers · https://platform.claude.com/docs/en/api/errors#request-id
Machine-readable: generated/fragments/headers/anthropic-headers.json
Last verified: 2026-09-18
Request headers
| Header | Required | Value / semantics | Live |
|---|---|---|---|
x-api-key |
yes, unless Authorization |
Console API key. Docs now call it the "legacy fallback" for Authorization, still fully supported (SDKs use it). |
✔; wrong key → 401 authentication_error "invalid x-api-key" |
Authorization: Bearer <token> |
yes, unless x-api-key |
API key or short-lived token: Workload Identity Federation (POST /v1/oauth/token) or ant auth login OAuth (ant auth print-credentials --access-token). SDKs: auth_token / ANTHROPIC_AUTH_TOKEN; Claude Code and Agent SDK use OAuth bearer tokens the same way. |
not tested |
anthropic-version |
yes | Only 2023-06-01 is current. Version preserves existing inputs/outputs; Anthropic may add optional inputs, output values and enum variants. |
2020-01-01 → 400 "is not a valid version"; 2023-01-01 → 400 "not allowed for this endpoint" |
content-type |
yes with body | application/json |
malformed JSON → 400 "The request body is not valid JSON: …" |
accept |
no | not required; streams are text/event-stream regardless |
✔ |
anthropic-beta |
no | comma-separated feature names, header may be repeated (all are read). SDK betas=[…]; CLI --beta a,b / repeated --beta. 46 values in the reference enum (owned by the models/beta fragment). |
unknown value → 400 "Unexpected value(s) … for the anthropic-beta header…"; context-management-2025-06-27 accepted on Haiku 4.5 |
anthropic-workspace-id |
required for multi-workspace keys | wrkspc_…; optional otherwise; not used with WIF. Also an SDK kwarg (workspace_id) and CLI --workspace-id. |
— |
anthropic-user-profile-id |
no (beta) | attribute the request to a user profile; needs user-profiles-2026-09-04 (or earlier) beta |
— |
Cloud platforms: Bedrock/Google Cloud/Foundry/Claude Platform on AWS use the provider's IAM (SigV4, OAuth) instead of x-api-key; Claude Platform on AWS adds x-amzn-requestid. See the cloud-platform docs (out of scope here).
Response headers
| Header | When | Semantics | Live (2026-09-18) |
|---|---|---|---|
request-id |
always | req_…; equals request_id in error bodies; SDKs expose _request_id / requestID; quote it to support |
✔ on 200, 400, 401, 404 |
anthropic-organization-id |
authenticated | org UUID of the credential | ✔ on 200/400/404; absent on 401 and on unknown-path 404 |
anthropic-workspace-id |
when the credential resolves to a workspace | wrkspc_… |
not observed on our key |
x-should-retry |
errors | undocumented in tables; false on every 4xx seen; SDKs honor true/false |
✔ false |
retry-after |
429/529 | seconds to wait; absent on tier spend-cap 429 (which "keeps failing until access resumes") | — |
anthropic-ratelimit-requests-{limit,remaining,reset} |
200 on Messages | RPM bucket, reset RFC 3339 | 10000 / 9999 / 2026-09-19T01:50:53Z |
anthropic-ratelimit-tokens-{limit,remaining,reset} |
200 | most restrictive token limit in effect, rounded to thousands | 12000000 |
anthropic-ratelimit-input-tokens-* / -output-tokens-* |
200 | ITPM / OTPM buckets | 10000000 / 2000000 |
anthropic-priority-input-tokens-* / -output-tokens-* |
Priority Tier only | presence = request eligible for Priority Tier (service_tier: auto) |
— (no commitment) |
content-type: text/event-stream |
stream: true |
SSE | ✔ |
CF-RAY |
always | Cloudflare edge id; 413 request_too_large is emitted by Cloudflare |
✔ (…-YUL) |
x-amzn-requestid |
Claude Platform on AWS | AWS request id (primary for CloudTrail) | n/a |
Observed limit values are account-specific (Build-tier key) — not documented limits. /v1/messages/count_tokens and /v1/models responses carried no anthropic-ratelimit-* headers.
Reading headers with the SDKs
Python: client.messages.with_raw_response.create(...) → .headers, .parse(); message._request_id. TypeScript: .asResponse() / .withResponse() → {data, response, request_id}; message._request_id. Go: option.WithResponseInto(&resp). Java: withRawResponse(). C#: client.WithRawResponse. PHP: $client->messages->raw. Ruby: per-request middleware.