Rate-limit headers

Syntic reports rate-limit state only when a request is refused. Successful responses carry no rate-limit headers, so a client cannot see how much of the minute is left ahead of time; it learns it has gone over from a 429, and from that response’s Retry-After.

On a 429 from the request cap

When a key (or a signed-in user) sends more than 600 requests within a sliding 60-second window, the API answers:

HTTP/1.1 429 Too Many Requests
Retry-After: 7
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset-Seconds: 7
x-syntic-request-id: req_6f1c2a9e0b7d4c3a8e5f1b2d
Content-Type: application/json
 
{"error":"Rate limit exceeded","scope":"api-proxy:apikey","retry_after_seconds":7}

Header	Value
`Retry-After`	Whole seconds to wait before trying again. Read this one first.
`X-RateLimit-Limit`	The cap that applied, `600`.
`X-RateLimit-Remaining`	Always `0`.
`X-RateLimit-Reset-Seconds`	Seconds until the window has room again; equal to `Retry-After`. There is no `X-RateLimit-Reset` header.

The body repeats the wait as retry_after_seconds.

On a 429 or 503 from the model service

A 429 or 503 can also come from further down the line, when the model service is busy. Those responses carry a Retry-After chosen by Syntic, kept within a sensible range, and no X-RateLimit-* headers. Treat them the same way: wait for Retry-After, then retry.

Reading the headers in a browser

Browser JavaScript cannot read the X-RateLimit-* headers, because they are not listed as exposed for cross-origin requests.

On develop, not live yet: Retry-After becomes readable from browser JavaScript. Until that ships, browser code should take the wait from retry_after_seconds in the 429 body, or fall back to a backoff delay.

Reading the wait

Check Retry-After first; fall back to your own backoff when it is missing.

curl -sS -D - -o /dev/null https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Amara Quick", "stream": false, "max_tokens": 16, "messages": [{"role": "user", "content": "ping"}]}' \
  | grep -i -E '^(retry-after|x-ratelimit)'

function waitSeconds(res: Response, attempt: number): number {
  const header = Number(res.headers.get('retry-after'))
  if (Number.isFinite(header) && header > 0) return header
  return Math.random() * Math.min(30, 0.5 * 2 ** attempt)
}

import random
 
def wait_seconds(res, attempt):
    header = res.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    return random.uniform(0, min(30, 0.5 * 2 ** attempt))

A full retry helper is on Rate limits & retries.

upstream_timeout Request IDs

Was this page helpful?