Rate limits

The Acme API rate limits requests per API key and HTTP method using a token bucket: the bucket holds your burst allowance and refills continuously at the sustained rate. Short bursts above the sustained rate are fine until the bucket is empty.

When you exceed a limit

The request is rejected with HTTP 429 and a Retry-After header (in seconds):

{
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "errorMessage": "Rate limit exceeded. Please try again later."
}

Bank rate limits

Some requests are forwarded to a bank, and the bank can rate limit them independently of your API key's bucket above. That case is also a 429 with the same errorCode, but errorMessage reads "The bank rate limited this request" (optionally with the bank's own wording appended) so you can tell the two apart:

{
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "errorMessage": "The bank rate limited this request."
}

Handling 429s

• Wait for the Retry-After interval before retrying instead of retrying immediately. For the per-API-key limit, the bucket refills within a second; for a bank rate limit, Retry-After is a fixed 2-second value, not the bank's own cooldown.
• A rate-limited request is never cached by idempotency, so retry it with the same Idempotency-Key.
• If your integration needs more sustained throughput, please contact Acme; limits can be raised per API key.