HTTP Headers

Reference the request headers OpenGateway accepts and the response headers it returns, including authentication, attribution metadata, budget notices, and retry guidance.

Use request headers to authenticate or attach metadata to usage records. Header names are case-insensitive. Do not put secrets in attribution values.

Request headers#

Authorization is required for inference endpoints. GET /v1/models is public. For POST /v1/messages, x-api-key can be used when Authorization is absent; an invalid Authorization value does not fall back to x-api-key.

Header	Purpose	Values
`Authorization`	Authenticates API requests.	`Bearer <API_KEY>`
`x-api-key`	Alternative authentication for `/v1/messages`, used only if `Authorization` is absent.	API key without the `Bearer` prefix.
`Content-Type`	Declares the request body format.	`application/json`; `/v1/images/edits` also accepts `multipart/form-data`.
`anthropic-version`	Optional Messages API version on `/v1/messages`; forwarded as provided.	Version date; defaults to `2023-06-01` when omitted.
`anthropic-beta`	Optional beta feature header on `/v1/messages`; forwarded as provided.	A beta feature token supported by the Messages API.
`x-opengateway-user-id`	Associates usage records with an end user.	Free-form identifier string.
`x-opengateway-session-id`	Associates usage records with a session.	Free-form identifier string.
`x-sionic-task-id`	Correlates related calls in usage records; the gateway generates an ID if omitted.	Free-form identifier string.

Response headers#

These headers are set by OpenGateway when relevant; do not send them as request settings.

Header	Purpose	Values
`X-OG-Traffic-Class`	Gateway-assigned traffic label. Treat it as informational and do not depend on its value.	For example, `PAID_STANDARD`; other labels are assigned by the gateway.
`X-OG-Budget-Warn`	Signals that a key with a configured budget has reached its warning threshold.	A generated usage percentage and tier marker; the marker is informational.
`X-OG-Warning`	Explains request parameters ignored without failing the request.	Text may name `temperature`, `top_p`, or both.
`Retry-After`	Indicates when to retry after some throttling or temporary errors.	Number of seconds to wait; present only when retry timing is available.

Examples#

Send attribution headers with a chat request:

Bash

curl "https://apis.opengateway.ai/v1/chat/completions" \
  -H "Authorization: Bearer $OPENGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-opengateway-user-id: user_42" \
  -H "x-opengateway-session-id: sess_a1b2c3" \
  -H "x-sionic-task-id: task_invoice_42" \
  -d '{"model":"openai/gpt-5-mini","messages":[{"role":"user","content":"Hello"}]}'

A throttled response may include a retry delay:

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>