Documentation
API limits
The API v1 limits are initial values published in the contract: every limited response carries RateLimit headers and, when you must wait, Retry-After; changing them does not break the API.
Rate limits
These numbers are initial values published in the contract. They are tuned with experience; changing them does not break the API.
Every response of a limited route carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 also carries Retry-After. Values are per window; the burst is what is allowed at once on top of the sustained pace.
| Rate limits | Window | Practice | Live | Burst |
|---|---|---|---|---|
| Every authenticated request, per key | 1 min | 120 | 60 | 30 |
| Request payments (`POST /v1/spends`), per agent | 1 min | 20 | 10 | 5 |
| Request payments per day, per agent | 1 day | 1000 | 200 | 0 |
| Check a payment (`POST /v1/spends/check`), per agent | 1 min | 60 | 30 | 10 |
| Administration writes (agents, rules, destinations, keys), per key | 1 min | 30 | 15 | 10 |
| Rotate or create keys per day, per owner | 1 day | 50 | 10 | 0 |
| Practice environment control (`/v1/test/*`), per owner | 1 h | 120 | 0 | 20 |
| Requests with an invalid or missing key, per IP | 10 min | 30 | 30 | 0 |
Headers
The limit headers in the API responses are:
RateLimit-LimitRateLimit-RemainingRateLimit-ResetRetry-After
Sizes
Maximum values of the request and of some fields.
| Sizes | Value |
|---|---|
| Request body | 16 KiB |
| `memo` | 280 characters |
| `client_reference` | 64 characters |
| `destination` | 253 characters |
| `resource` URL | 2048 characters |
| Items per page (default) | 10 items |
| Items per page (maximum) | 50 items |
| Long wait (`wait_seconds`) | 20 seconds |
| Idempotency key memory (minimum) | 24 hours |
| Lifetime of a pending approval (default) | 15 minutes (5-60) |
| Duplicate purchase warning window | 60 seconds |
| Lifetime of a practice key (default) | 90 days |
| Lifetime of a live key (default) | 30 days |
| Overlap when rotating a key (maximum) | 7 days |
Quotas
Caps on how many things each owner can have.
| Quotas | Value |
|---|---|
| Active agents in practice | 5 |
| Active agents in live | 10 |
| Archived agents | 20 |
| Active keys per agent | 3 |
| Active owner keys | 3 |
| Webhook endpoints | 10 |
| Days events are kept | 30 |
Idempotency
- With the same key and the same fingerprint (amount, currency, destination and resource), the API gives back the current state of the same payment with
idempotent_replay: true, without paying again. memoandclient_referenceare not part of the fingerprint: a model rewrites them every time it retries.- The same key with a different fingerprint gives 409
idempotency_conflict;changed_fieldssays what changed. - A
failedpayment leaves the key spent: a new attempt needs a new key.
Webhooks
- Maximum response time of the endpoint: 5 seconds.
- Attempts per delivery: 8, over about 24 hours.
- After 20 failures in a row the endpoint is paused and the owner is told.