Docs
Request and response headers
Every HTTP header the gateway reads from your requests or adds to its replies, what each one does and where it is described in full.
Updated
Most clients never need a header beyond the API key. The ones below are for tracking calls, steering routing and reading limits without an extra request. Header names are not case-sensitive.
Headers you can send
| Header | What it does |
|---|---|
Authorization: Bearer <key> | Your API key. x-api-key and x-goog-api-key are accepted too. Details |
X-Client-Request-Id | Your own id for the request (printable ASCII, up to 128 characters), for feedback and the request lookup. Details |
X-Title | Your app or tool name. Used to group usage by coding tool; the header itself is not stored. Details |
X-Session-Id | Groups requests into one session on the usage page. Details |
X-Fallback-Models | Up to 3 comma-separated model ids tried in order when the provider fails before answering. Details |
X-Metadata | A JSON object (up to 4096 characters) read by the routing rules of a virtual model. Details |
X-Auto-AllowX-Auto-Deny | Narrow automatic model choice: up to 20 comma-separated model ids, * matches any text. Details |
X-Tag | Your own label for the call (printable ASCII, up to 64 characters). Usage > Tags shows spend per tag. Details |
X-Request-Timeout | Milliseconds (1000 to 600000) to wait for the reply to start; after that you get 408. Details |
X-Response-Healing: on | Repairs a JSON-mode reply that does not parse (non-streaming). Details |
X-No-Log: true | Leaves this call out of the key’s prompt log. Details |
X-Coupon | off keeps coupon credit out of this call, so your balance or plan pays; a code makes that coupon pay for the call. Case and spaces are ignored. Not read for free models. Details |
Headers in the reply
| Header | What it holds |
|---|---|
X-Request-Id | Replies from the model. The request id. Quote it to support, score the answer with it or look up its cost. Details |
x-ratelimit-limit-requestsx-ratelimit-remaining-requestsx-ratelimit-reset-requestsx-ratelimit-policy | Keys with a requests-per-minute limit. The limit and what is left, after this request. Details |
x-key-budget-limitx-key-budget-remainingx-key-budget-reset | Keys with a spend budget. The budget and what was left before this request’s cost, in USD; the reset in Unix seconds. Details |
X-Daily-LimitX-Daily-RemainingX-Daily-Reset | Models with a daily cap. The cap, what is left today and the next reset (00:00 UTC) in Unix seconds. Details |
Retry-After | A 429 from a daily cap, key limit or spend limit. Seconds to wait before trying again. Details |
X-Fallback-From | Your fallback model answered. The model that failed. Details |
X-Tools-Dropped: 1 | The request was resent without tools. The model refused tool calling, so tools were removed. Details |
X-Virtual-Model | The request named a virtual model or an auto model. The name you sent; the reply’s model field names the model that answered. Details |
X-Route-Rule | A routing rule matched. The rule’s number, 1 for the first. Details |
X-Canary: 1 | The canary model was tried first. The request was picked for the canary. Details |
X-PII-Redaction | PII redaction is on for the key. What was redacted: input, output, or input, output. Details |
X-Guardrail | A guardrail logged a match and let the request pass. The checks that matched. Details |
X-Context-Trimmed | A middle-out trim shortened the conversation. How many messages were removed or shortened so the prompt fits the context window. Details |
X-Coupon: 1 | A coupon paid for the request. Coupon credit paid for this call, not your plan or balance. Details |
Replies do not carry a cost header: a request’s price is only final once the reply has finished. To see what one request cost, look it up by its id, or read the usage object in the reply and the prices on the model list.
See the headers of a reply
-D - prints the reply’s headers and -o /dev/null hides its body:
curl -sS -D - -o /dev/null https://api.oneaiapikey.com/v1/chat/completions \
-H "Authorization: Bearer $ONEAIAPIKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "glm-5.3-flash:free", "messages": [{"role": "user", "content": "Hi"}]}'In the OpenAI Python SDK, client.chat.completions.with_raw_response.create(...) returns the reply with its headers.
Related
- Rate limits and retries: limits, budgets and what to do on a
429. - Routing and privacy: fallback, virtual models, redaction and what is recorded.
- API reference: every endpoint and field.