Skip to content

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 the Retry-After header 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

ResourceLimit
Active API keys20 per workspace. Revoke one to create another.
Active webhook endpoints5 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 obligations come from the latest completed cycle snapshot, and are null until 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.

Edit this page on GitHub (opens in a new tab)