The OneBalance API implements rate limiting to ensure fair usage and availability of the service for all users. Rate limits are applied on a per-API key basis.

​
Current Rate Limits

User TypeRequest Rate LimitConcurrent Connections
Public API Key60 requests per minute1 per IP address
Authenticated UsersCustom rate limitsCustom limits
Authenticated users receive higher rate limits based on their specific needs. Please contact our team if you require increased limits for your production application.
Once you exceed your limit, your requests will be temporarily rejected until the rate limit window resets.

​
Rate Limit Headers

The rate limiting information is included in the response headers of each request:
HeaderDescription
x-ratelimit-limitThe maximum number of requests you’re permitted to make per minute
x-ratelimit-remainingThe number of requests remaining in the current rate limit window
x-ratelimit-resetThe time at which the current rate limit window resets in Unix epoch seconds
As long as the x-ratelimit-remaining count is above zero, you’ll be able to make additional requests.

​
How Rate Limiting Works

Each request contributes toward your rate limit count for one complete minute. This means that the entire rate limit doesn’t reset at once. Rather, each request expires individually one minute after it was made. The value of the x-ratelimit-reset header indicates when the oldest request will expire and no longer count toward your limit.

​
Handling Rate Limits

If you exceed the rate limit, the API will return a 429 Too Many Requests status code. We recommend implementing the following strategies to handle rate limits effectively:
  1. Monitor the rate limit headers in your API responses to track your usage
  2. Implement exponential backoff when receiving 429 responses
  3. Pace your requests to avoid hitting the limits, especially for batch operations
  4. Cache responses when possible to reduce the number of API calls

​
Sample Rate Limit Headers

Terminal
x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 60

​
Sample Rate Limit Exceeded Response

Rate Limit Exceeded
{
  "error": "TooManyRequests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "statusCode": 429,
  "timestamp": "2024-12-18T14:38:24.793Z",
  "path": "/api/assets/list"
}

​
Best Practices

  • Space out requests that would otherwise be issued in bursts
  • Implement retry logic with exponential backoff when receiving 429 responses
  • For high-volume operations, consider batching requests where appropriate
  • Use the public API key for testing and development only, as it has lower rate limits
Some endpoints may have special rate limit requirements that are independent of the general limits defined above.