Skip to main content

API Configuration and Limits

Use these limits to plan request rates for creating transfers, reading balances, and checking transfer status.

Request rates​

Each operation allows up to 3 requests per second (RPS) per API key. The limit applies separately to each operation.

OperationRequests per second per API key
POST /v1/transfers3
GET /v1/transfers/{transfer_id}3
GET /v1/accounts/{account_id}/balance3
Requests using the same API key

All applications and workers using the same API key share the limit for each operation. Requests for different accounts or transfers still count toward that operation's limit.

  1. 1
    Prepare credentials and confirm your setup with Send Your First Request.
  2. 2
    Configure request rates for each operation and API key using the table above.
  3. 3
    Count requests from all applications and workers using the same key. Include status checks and retries.
  4. 4
    On HTTP 429, wait before retrying and reduce the request rate.

Request scheduling​

Spread requests over time and coordinate the applications and workers that use the same API key.

For example, status requests for three different transfers count toward the same 3 RPS limit for that API key. Balance reads and transfer creation each have their own 3 RPS limit.

Each retry is another API request, even when it uses the same idempotency key. Include retries when counting requests for the operation.

We recommend checking the transfer status every 2 seconds while it is processing. Stop checking when it reaches done or rejected. Keep the total number of status requests for your API key within 3 RPS, even when checking several transfers. See Check a Transfer Status.

Rate-limit errors​

On HTTP 429 with code 3015 / REQUEST_RATE_LIMIT, wait before sending another request. All codes are listed in Troubleshooting Your API Requests.

During periods of high load, the API may return HTTP 429 even when your request rate is below 3 RPS. Handle these responses in the same way.

  • Reduce the request rate

    Pause requests for the affected operation. If rate limiting continues, wait longer between retries (backoff). Include requests from other workers using the same API key.

  • Reuse the idempotency key

    For a retry of POST /v1/transfers, reuse the same idempotency key and the exact same request. Generate a fresh timestamp and signature for each attempt.

  • After an unknown outcome

    After an unknown outcome, the transfer may still exist even if a retry returns a rate-limit error. Follow Recovery and idempotency.