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: 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: Are limits applied per endpoint or across all endpoints? A: We apply limits at the domain level (e.g. ACH vs Core) and further separated by operation type (GET vs PUT for example).
Q: Can my rate limits be adjusted? A: Yes. If your business needs require higher limits, please contact your relationship manager to discuss options.
Q: How are limits measured? A: Measurement windows vary by domain. We measure some domains on a per-minute basis, while we measure others on a per-second basis.