API rate limiting
Overview
Cross River's API rate limiting controls how many requests you can make. We set these limits within defined timeframes. This ensures platform stability, fair resource distribution, and consistent performance for all partners.
We apply rate limits per partner and configure them across different programs (for example ACH or Instant payments). When your application exceeds its assigned rate limit, the API returns an HTTP 429 — Too Many Requests response.
How it works
Each API request from your application follows this flow:
- Request received: Your request arrives at Cross River's API gateway.
- Client identified: The system identifies your application via Partner ID.
- Limit checked: We check your usage against your rate limit.
- Request processed or rejected:
- ✅ If within limits, we process your request normally and return the expected response.
- ❌ If limits exceeded, the API returns an HTTP 429 Too Many Requests response.
- Usage feedback: HTTP response header provides information on current usage status. Monitor these headers and back off before hitting HTTP 429.
Response header
Header | Meaning |
|---|---|
x-ratelimit-reset | How long (in seconds) until the window resets |
x-ratelimit-limit | Total limit: how many requests this partner is limited to |
x-ratelimit-remaining | How many requests this partner has remaining in the current window |
Best practices
To make the most of your rate limits and avoid disruptions:
Practice | Description |
|---|---|
Implement retry logic | Use exponential backoff when receiving 429 responses. Wait longer between each retry. |
Batch/bulk where possible | Combine operations into batch or bulk requests. For example, use send ach batch to batch ACH payments. This reduces total API calls. |
Cache responses | Cache frequently accessed data (for example account details) to reduce redundant read calls. |
Monitor usage | Check the rate limit response headers included in each API call to track your current usage against your configured limits. Contact your relationship manager if you need details on your rate limit profile. |
Optimize integrations | Audit your integration for unnecessary or duplicative calls that consume your quota. |
FAQ
Q: What is the default hard limit?
A: The default hard limit is 400 requests per second.
Q: Are limits applied per HTTP methods or across all HTTP methods?
A: There are separate counters for GET requests versus POST/PUT requests, meaning each counter allows up to 400 requests per second.
Q: Are limits applied per endpoint or across all endpoints?
A: The default hard limit of 400 requests per second is shared across all applicable endpoints.
Q: How do I know what my rate limits are?
A: Your rate limits are communicated via response headers on every API call. Your relationship manager can also provide details on your configured limits.
Q: What happens when I hit my limit?
A: Requests exceeding your limit will receive an HTTP 429 response. Requests will succeed again once your usage drops back within the allowed threshold.
Q: Why am I getting 429s when my logs show I stayed under the limit?
A: We measure rate limits when requests arrive at our servers, not when your application sends them. Network latency and retries can bunch requests together. They may land in different measurement windows than you expect. The response headers returned on each call reflect what our systems actually counted, so monitor the response headers closely.
Q: Can my rate limits be adjusted?
A: Yes. If your business needs require higher limits, please contact your relationship manager to discuss options.