Rate limits and retries
Bound request volume and retry transient failures with stable economic identities.
Use bounded concurrency and backoff. A faster retry loop does not make your operator approve or send sooner, and replacing idempotency keys can create unintended rewards.
Initial product limits#
| Limit | Initial value |
|---|---|
| Authorized API requests | 120 per minute per project. |
| Issuance request body | 16 KiB maximum. |
| List page size | Default 50; minimum 1, maximum 100. |
| Idempotency key | 8–128 permitted characters. |
| Event ID | 1–128 characters. |
| Event type | 1–64 permitted characters. |
| Draft campaign | Up to 100 recipients on one asset, one transfer per recipient. |
These are initial Slices defaults, not vendor limits, guarantees of sustained throughput, or a reason to send bursts at the ceiling. Confirm the active limits supplied for your approved deployment.
All requests from a project share its allowance. Creating extra keys is not a way to bypass the project limit. Coordinate reads, writes, retries, and status jobs across your /v1 integrations. The dashboard uses a separate internal console interface; do not assume its request policy is the partner API policy.
Handle 429#
A throttled response uses RATE_LIMITED and includes Retry-After. Respect the bounded indicated delay, reduce concurrent work, and add jitter so workers do not all retry together.
If you cannot determine a usable retry delay, use a bounded exponential backoff policy and surface repeated throttling. Never retry in an unbounded loop.
Retry matrix#
| Outcome | Automatic retry policy |
|---|---|
| Transient network failure or timeout | Bounded retry; writes must preserve the same key and request. |
429 | Honor Retry-After within configured bounds and reduce load. |
502, 503, 504 | Bounded retry with jitter. |
400, 401, 403, 404, 409, 422 | Do not automatically retry unchanged. Investigate the error. |
Generic 500 | Not included in the default automatic retry set; use request-ID diagnostics and safe outcome recovery. |
| Caller abort | Stop the request and any retry sleep. The server may already have committed. |
An automatic retry policy and a manual reconciliation policy are different. Not automatically retrying a 500 does not mean a fresh key is safe. Preserve the original identity and inspect or replay it deliberately.
Avoid layered retry storms#
The SDK can retry transient requests. Your queue or job runner may also retry failed jobs. Account for both layers so one incident does not multiply traffic unexpectedly.
Persist the instruction once and let every attempt use that same record. Use a finite job retry budget and a visible exception queue for instructions that still need attention.
Poll efficiently#
Do not poll every outstanding reward every second. Use scheduled backend refresh, cache results for your frontend, and page through filtered lists where that fits your reporting needs.
List pagination is not an atomic batch-issuance interface. To send many calculated allocations, call issuance once per allocation through a bounded worker pool and preserve individual outcomes.
Capacity rejection is not rate limiting#
BUDGET_EXCEEDED means authorized net issuance capacity is exhausted. GRANT_LIMIT_EXCEEDED means one instruction is too large. Sleeping and repeating does not necessarily fix either condition, and splitting requests solely to evade the limit is not an acceptable recovery method.
Related: Idempotency, Track rewards, and Errors.