Rate limits

Rate limits are enforced per API key. Exceeding a limit returns 429 Too Many Requests with a Retry-After response header that tells you how long to wait before retrying.

Response shape

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

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 30 seconds."
  }
}

Retry-After is in seconds. Wait at least that long before retrying. A client that ignores Retry-After and keeps hammering will simply continue to see 429s.

Best practices

• Respect Retry-After. Don't retry on a 429 without waiting for the specified delay.
• Add jitter on backoff. For high-concurrency callers, jitter on the retry delay prevents thundering-herd behaviour when many clients see 429 at once.
• Use separate keys for separate callers. Quotas are per-key, so one noisy caller can't starve another if they're on different keys.
• Poll at the slowest cadence you can tolerate. For intent status polling, 5–10 seconds is typically fine while an intent is in flight; back off to 30+ seconds once it enters a long-running state (requires_compliance, paying_out).

Gotchas

• 429 is transient. Unlike 401 / 403, a 429 does not mean the credentials are wrong — just that too many recent requests used them. Retry with backoff.
• Retry-After applies to the single failed call, not the account. After waiting, you can retry that request; other requests may succeed sooner depending on the specific quota that tripped.

See also

• Error handling — other status codes and when to retry
• Authentication — quotas are per-key