Rate Limits & Headers

Onlist returns a small set of custom response headers and uses standard HTTP status codes for back-pressure. There is no separate quota API to poll and no bespoke SDK — everything you need to correlate a request, react to ignored fields, or back off is on the response itself.

Response headers

Onlist adds three headers on top of the usual OpenAI-compatible response. None of them are required to make a request work, but each is useful for observability and correct retry behavior.

X-Onlist-Route-Id

X-Onlist-Route-Id is an opaque UUID that identifies the routing decision Onlist made for your request. It is written on both streaming and non-streaming responses — on a stream, it is set before the first SSE byte, so it is available as soon as headers arrive.

This is not the response body id field. The body id is the upstream completion id (issued by whichever provider served you); X-Onlist-Route-Id is Onlist's own identifier for which provider and listing were selected.

To inspect the routing decision later, look it up via the authenticated, owner-only endpoint:

GET /api/mkt/routes/{route_id}
Authorization: Bearer YOUR_ONLIST_TOKEN

Only the buyer who made the request can read their own route records. This is also how you correlate a request to its cost — see Usage & cost, since cost is not returned in the response body.

X-Onlist-Warnings

Onlist accepts the full OpenRouter-style provider object, but fields it does not act on are silently ignored rather than rejected — you get a 200, not a 400. When that happens, the ignored fields are reported in X-Onlist-Warnings so the behavior is never invisible.

The header value is a single string: a comma-and-space (, ) joined, de-duplicated list of entries. Each entry is either:

• an ignored: <field> marker, e.g. ignored: provider.sort or ignored: provider.only[1:3]; or
• a routing notice, e.g. cool_pool_exhausted_fallback_used.

X-Onlist-Warnings: ignored: provider.sort, ignored: provider.zdr, ignored: provider.only[1:3]

The header is present only when something was ignored or a notice fired — a clean request returns no X-Onlist-Warnings header at all. Parse it by splitting on the literal string , (see Reading the warnings header below). For the full list of which provider fields are honored versus ignored, see Provider routing.

Rate limiting

Onlist enforces a per-token rolling-window cap. Each API token has its own limit; exceeding it within the window returns 429 with the rate_limited error code and a Retry-After header telling you how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": {
    "message": "rate limit 1d exhausted (10000/10000), retry after 42s",
    "type": "onlist_error",
    "code": "rate_limited",
    "param": ""
  }
}

Because the window is rolling, capacity returns gradually rather than resetting all at once at a fixed boundary. Honor the Retry-After value: it is the server's estimate of when you can safely try again.

Cooldown

Separately from rate limiting, a selected provider or listing can be in cooldown — for example after a run of upstream failures. When the eligible pool for your request is unavailable for this reason, Onlist returns 503 with a Retry-After header.

HTTP/1.1 503 Service Unavailable
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "message": "all matching listings have disabled upstream channels",
    "type": "onlist_error",
    "code": "no_provider_available",
    "param": ""
  }
}

Not every 503 carries a Retry-After: it is emitted specifically when the cause is a cooldown. Other 503 conditions — no_provider_in_max_price (your max_price filtered the whole pool) and no_provider_after_allow_deny (your allow/ignore preferences excluded every provider) — reflect your request constraints rather than transient unavailability, so retrying the same request without changing it will not help. See Errors for the full status-code and error-code reference.

Reading the warnings header

X-Onlist-Warnings is a flat string. To turn it into a list you can branch on, split on the literal , separator. The header is absent when there is nothing to report, so guard for the missing case.

# Print the warnings header (if any) from a single request.
curl -sD - -o /dev/null https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i '^x-onlist-warnings:'

In production, log X-Onlist-Route-Id alongside each request so you can correlate it to cost and routing metadata, and surface X-Onlist-Warnings during development so you notice when a provider field you set is being ignored.

Next steps

• Provider routing — Which provider fields are honored, and which are accepted-but-ignored and reported in X-Onlist-Warnings.
• Errors — The error envelope, every status code, and the stable error code slugs to branch on.
• Usage & cost — Token usage fields and how to correlate a request to its cost via X-Onlist-Route-Id.
• OpenAPI spec — Full request and response schemas, including every response header (YAML download).