Rate limiting

Nexpay enforces rate limits to protect the API from abuse and ensure consistent performance for all users. When you exceed a rate limit, the API responds with HTTP 429 Too Many Requests.

Default limits

The API applies a global rate limit of 200 requests per second per client. This limit applies to all endpoints unless a stricter per-endpoint limit is in place.

Per-endpoint limits

Some endpoints have stricter limits to prevent abuse:

Handling rate limit errors

When you exceed the rate limit, the API returns a 429 status code:

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Best practices

• Implement exponential backoff — When you receive a 429 response, wait before retrying. Start with a short delay (e.g. 1 second) and double it on each consecutive 429 response.
• Cache responses — Avoid unnecessary repeated requests by caching responses locally, especially for data that doesn't change often (e.g. lookup data, payee lists).
• Spread requests over time — If you need to make many requests (e.g. bulk imports), spread them evenly rather than sending them all at once.
• Use query parameters efficiently — Retrieve multiple records per request using pagination instead of fetching them one by one.

Retry example

const fetchWithRetry = async (url, options, maxRetries = 3) => {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise((resolve) => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
};