Limits
Page sizes, backing off on 429 and 503, and how fresh the data is.
What the API bounds today, what it does not, and how fresh its data is.
Page size
A collection returns 1 to 200 items per page. limit defaults to 50, and a larger value than 200 is capped at 200 rather than refused. Every page is bounded, so no single request reads a whole ledger. Pagination covers the rest.
Rate limits
Reads have no rate limit, except the evidence reads: a payment's evidence or receipt, the payee lock's evidence and a monthly close pack. Each reads and checks many signed entries, so one key makes up to 10 of them at once, then one every 6 seconds, counted on each server instance; over that they answer 429 rate_limited with Retry-After: 60. Writes from one key come in bursts of up to 30, then one every 2 seconds, counted on each server instance, so a key can make up to about 60 writes in its first minute and a little more now and then. Over the limit, a write answers 429 rate_limited with Retry-After: 60. No endpoint returns 503 today, but unavailable is a defined error code: write your client to back off on both, and it keeps working if a limit is added to other reads.
- On a
429, wait at least as long as theRetry-Afterheader says, in seconds, before you try again. - On a
503, retry with exponential backoff.
Poll no more often than you need to. To react to each new ledger entry, webhooks push it to you, so you do not need to poll the ledger quickly.
Request bodies
A write's body is one JSON object of at most 64 KB. A body that is larger, is not JSON, or has a field the operation does not take answers 400 invalid_request, and nothing is written. To make a retry safe, send an Idempotency-Key: Retrying safely explains it. A payee link takes none: a repeat makes a new link, which replaces the first.
Response size
A close pack, or the payee lock's evidence for a long period, whose answer would be over 4 MB answers 400 invalid_request. Download such a close pack from the workspace's Monthly close pack page, or ask for the payee lock's evidence a shorter period at a time.
Keys and endpoints per workspace
| Resource | Limit |
|---|---|
| Active API keys | 20 per workspace. Revoke one to create another. |
| Active webhook endpoints | 5 per workspace. |
Freshness
Data is read live on each request: responses are not cached, so an invoice, a decision or a payment is visible on the next request after it is recorded.
Two endpoints report on the latest cycle rather than on this moment:
- Treasury's
obligationscome from the latest completed cycle snapshot, and arenulluntil one exists. - Insights reports the telemetry of recent cycles, transfers and screenings.
Response shapes
Every endpoint answers with the documented envelope: data, plus page for a collection, or error. New fields can be added to v1 responses, so ignore fields you do not know rather than rejecting the response. A field is not removed from, or changed in, v1 without an entry in the changelog.