17. 429 - rate limited (per-token cap)

The API key has exceeded its per-second request quota. Limits are per token, not per instance - if you have several services sharing one token, they share the budget. The response includes both the standard Retry-After header and a retry_after_seconds body field.

See /docs/rate-limits for the full reference (per-tier caps, burst behaviour, headers).

Any request after the per-token cap is hit. -i shows the headers.

curl -i -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1"}'

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

{
  "error": "rate_limited",
  "message": "API key has exceeded its per-second request quota",
  "retry": true,
  "retry_after_seconds": 7
}

• Sleep for Retry-After seconds before retrying. Don't tight-loop.
• The SDKs honour Retry-After automatically with exponential backoff and jitter.
• If you're consistently hitting the cap, raise the tier (each tier has a higher per-token quota) or split traffic across multiple tokens.
• Audit for accidental hot loops - a misbehaving worker spinning at 10k req/s is the usual cause.
• retry: true - after the indicated wait.