# 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.