Rate limits - SODACARDS

Requests are rate-limited per API key. The budget is advertised on every response in the RateLimit-Policy header:

RateLimit-Policy: "per-key";q=600;w=60

That is 600 requests per 60-second window for the key. The window is a rolling budget, not a fixed clock minute.

When you exceed it

A request over budget is refused with 429 Too Many Requests. The response carries a Retry-After header — a whole number of seconds to wait — alongside the usual RateLimit-Policy:

HTTP/2 429
RateLimit-Policy: "per-key";q=600;w=60
Retry-After: 12
Content-Type: application/problem+json

{
  "type": "https://developer.sodacards.com/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request rate for this key. Retry after the indicated delay.",
  "request_id": "..."
}

Backing off

Wait for the number of seconds in Retry-After before retrying.
Prefer a small concurrency and steady pace over bursts.
Spread scheduled work; do not fire a whole batch at the top of the minute.
Reuse a single key’s budget deliberately across your workers.

Reveal has its own, tighter throttle. Revealing an order’s codes too often returns reveal_rate_limited; see Errors.