Rate limiting
Rate limiting is a mechanism applied by API providers to restrict the number of requests a client can make within a defined time window, protecting infrastructure stability and ensuring fair resource allocation across all API consumers, typically enforced by returning HTTP 429 errors when limits are exceeded.
Payment API rate limits protect infrastructure from overload, whether from unintentional load, such as a loop bug submitting thousands of requests per second, or malicious activity. Rate limits are typically expressed as requests per second, per minute, or per hour, applied at the API key, endpoint, or account level.
Rate limit design varies by API operation. Read operations (checking payment status, retrieving transaction history) typically have higher rate limits than write operations (initiating payments, creating cards). Batch APIs that accept multiple operations per call are a common way to work within rate limits for high-volume use cases.
Handling rate limits correctly in client integrations requires exponential backoff: when a 429 response is received, the client waits an increasing period before retrying rather than immediately retrying, which would hit the rate limit again. Production payment integrations should monitor rate limit headers returned by APIs and proactively throttle request rates before limits are reached.
Rate limits protect the reliability of payment infrastructure for all users. Without rate limits, a single misbehaving client could degrade API performance for the entire platform. For client integrations, understanding rate limits is essential for designing integrations that handle high volumes efficiently, using batch APIs where available, implementing correct backoff strategies, and monitoring API usage against limits.
- Rate limit handling requires implementing exponential backoff retry logic correctly
- Burst API calls (end-of-month payroll processing) may hit rate limits even at legitimate volumes
- Rate limit responses must be distinguished from payment failures requiring different handling
- Monitoring API usage against limits requires instrumentation in the client application
- Multi-tenant platforms sharing an API key must manage aggregate request rates
A payroll platform processing 80,000 salary payments at month-end implements a rate-limit-aware submission queue. Payments are submitted at a controlled rate below Nium's rate limits, with automatic pause-and-retry on 429 responses using exponential backoff. The full batch completes in 4 hours without any rate limit errors, compared to the previous approach that required manual intervention to resume.
Related Concepts
Nium's APIs implement rate limiting to protect platform stability. Rate limit details are documented in Nium's developer portal. API responses include rate limit headers indicating current usage and remaining capacity, enabling client applications to monitor usage and throttle request rates proactively. Batch payout APIs support high-volume processing within rate limit constraints.
Answers you didn't know you needed.
What is a 429 error?
HTTP status code 429 means 'Too Many Requests': the client has exceeded the API rate limit. The response may include a 'Retry-After' header indicating how long to wait before retrying. Client applications should implement retry logic that waits the specified duration before resubmitting.
What is exponential backoff?
Exponential backoff is a retry strategy where wait times increase exponentially after each failure: wait 1 second, then 2, then 4, then 8, etc. Adding random jitter prevents multiple clients from retrying simultaneously after a rate limit event.
Are rate limits applied per API key?
Typically yes, rate limits are applied per API key, allowing different clients to have independent limit allocations. Check Nium's documentation for specific rate limit configurations.
Can rate limits be increased?
Many API providers offer higher rate limits for clients with legitimate high-volume requirements. Contact Nium's team to discuss rate limit increases if your use case requires higher throughput than the default configuration.
How do I avoid hitting rate limits in production?
Monitor API usage against limits using rate limit headers in responses. Use batch APIs where available. Implement request queuing to smooth out burst loads. Use exponential backoff retry logic as a safety net.