API Rate Limits

Every request to the API passes a process-wide limiter of 20 requests per second per client address. Sensitive operations carry a second budget on top of it, counted per organization or over a longer window. The two count different things: the process-wide limiter bounds throughput, and an operation budget bounds how often one caller may do one expensive thing.

Both apply at once. The process-wide budget is counted per client address; an operation budget is counted per organization on API key requests and per user on dashboard requests. A limit applies to the whole platform, so a request does not get a fresh budget by reaching a different server.

Request budgets

Export and credential budgets

Three operations mint or retire something that cannot be taken back, so their budget counts how often, not how fast. Waiting does not earn a faster caller more of them.

Response headers

Every response carries the state of the process-wide budget for the calling address:

A refused request also carries Retry-After, in seconds, which says when that budget recovers.

429 response

A refused request returns 429 Too Many Requests with the standard error envelope:

Code
{
  "success": false,
  "errors": {
    "method": "POST",
    "path": "/v2/customers/665f1a2b3c4d5e6f708192a3/export-private-keys",
    "message": "Too many private key export requests, please try again later"
  },
  "status": 429
}

The message names the budget that refused the request, so a client can tell a throughput problem from a spent capability budget.

Handling a 429

1. Read Retry-After when it is present and wait that long. Otherwise read RateLimit-Reset.
2. Retry with exponential backoff. Do not retry in a tight loop.
3. Use Webhooks instead of polling for transaction and wallet state changes.
4. Send an idempotencyKey on every state-changing request. A retry after a refusal then runs once.

Scope

This page covers the API key surface. Endpoints outside it are not described here.

The security model describes where DDoS filtering sits, ahead of these budgets.