Status: documented headers DOCUMENTED; every header marked observed was seen in our own responses on 2026-09-18 (LIVE_VERIFIED); openai-project, x-should-retry, retry-after-ms, CF-RAY are LIVE_DISCOVERED (observed / SDK source, not on the docs pages). Idempotency-Key is not an OpenAI header (UNVERIFIED/absent from spec).
Sources: API overview → Request headers / Debugging requests · Rate limits → headers · Webhooks guide · Realtime WebSocket guide · SDK sources (openai/_base_client.py, openai/client.js).
Last verified: 2026-09-18. Machine-readable: generated/fragments/headers/openai-headers.json (32 records).
| Header |
Required |
Values / rules |
Verified |
Authorization |
yes |
`Bearer <sk-proj-… |
sk-… |
Content-Type |
yes (bodies) |
application/json; multipart/form-data for uploads; application/sdp (Realtime WebRTC) |
observed: text/plain → 400 unsupported_content_type |
OpenAI-Organization |
no |
org id; must match the key's org |
observed: mismatch → 401 mismatched_organization |
OpenAI-Project |
no |
project id (legacy user keys) |
observed: unknown → 401 invalid_project |
OpenAI-Beta |
per surface |
assistants=v2 (legacy Assistants), agents=v1 (Agents API), chatkit_beta=v1, responses_multi_agent=v1, workspace_agent_runs=v1, realtime=v1 (legacy Realtime beta) |
documented; invalid_beta 400 observed by another agent |
X-Client-Request-Id |
no |
your correlation id, ASCII, ≤ 512 chars, unique |
observed: non-ASCII → 400; accepted otherwise, not echoed |
Accept |
no |
text/event-stream implied by stream: true |
documented |
User-Agent + X-Stainless-* |
SDK |
telemetry (X-Stainless-Lang, -Package-Version, -OS, -Arch, -Runtime, -Runtime-Version, X-Stainless-Retry-Count, X-Stainless-Timeout) |
SDK source |
Idempotency-Key |
— |
not supported/documented; dedupe yourself (metadata, Batch custom_id, webhook webhook-id) |
absent from spec |
| Size budget |
— |
all headers < 64 KiB; custom header values ≤ 60 KiB total |
documented |
Realtime WebSocket: server side Authorization: Bearer …; browsers pass the ephemeral key as subprotocol realtime, openai-insecure-api-key.<ek_…>; legacy beta also OpenAI-Beta: realtime=v1.
| Header |
Meaning |
Observed value (2026-09-18) |
x-request-id |
request id for support; SDK response._request_id / _request_id |
req_b02412ebc5604692b13b994c52e5e674 on chat/completions, responses, audit_logs; UUID form (bc452ff1-…) on models, webhook_endpoints, organization/*; absent on edge 404 (unknown URL) |
openai-processing-ms |
server processing time |
2 … 582 |
openai-version |
REST API version |
2020-10-01 (also on 4xx) |
openai-organization |
billed org |
present on model calls, admin 403s; absent on 401s and GET /v1/models/{id} |
openai-project |
project of the key (not documented) |
proj_… alongside openai-organization |
x-ratelimit-limit-requests / -tokens |
RPM / TPM ceilings for the model |
30000 / 150000000 (gpt-4.1-nano) |
x-ratelimit-remaining-requests / -tokens |
remaining in window |
29999 / 149999995 |
x-ratelimit-reset-requests / -tokens |
Go duration until reset |
2ms / 0s (docs: 1s, 6m0s) |
x-ratelimit-limit-project-tokens, -remaining-project-tokens, -reset-project-tokens |
only when a project token limit applies |
not present on our project |
Retry-After |
seconds to wait; on 429 (temporary limit / slow_down) and 503 (server_is_overloaded); never for quota/billing |
not triggered |
retry-after-ms |
ms variant parsed by SDKs first |
SDK source |
x-should-retry |
true/false overrides SDK retry decision |
SDK source |
CF-RAY |
Cloudflare trace id (…-YUL = Montréal edge) |
on every response incl. bodyless 404 |
Content-Type |
application/json; text/event-stream for streams |
observed |
Location |
Realtime WebRTC POST /v1/realtime/calls → /v1/realtime/calls/{call_id} |
documented |
Rate-limit headers appear on model endpoints even when the request fails validation (seen on the 400 invalid_value chat/completions probe) — a rejected request still consumed a request slot (remaining-requests: 29999).
| Header |
Value |
webhook-id |
wh_… unique delivery id (dedupe key; part of the signed string) |
webhook-timestamp |
unix seconds; SDK tolerance ±300 s |
webhook-signature |
v1,<base64 HMAC-SHA256> list, space separated |
user-agent |
OpenAI/1.0 (+https://platform.openai.com/docs/webhooks) |
content-type |
application/json |
| Status |
x-request-id |
openai-organization/-project |
rate-limit headers |
| 400 validation on model endpoint |
yes (req_…) |
yes |
yes |
| 401 auth failures |
yes (UUID) |
no |
no |
403 admin scope (/organization/*) |
yes (UUID) |
yes (except certificates) |
no |
| 404 unknown URL |
no (only CF-RAY) |
no |
no |
| 405 wrong method |
yes |
— |
no |