Understanding rate limits and pagination helps you build robust integrations with the Avala API.
Rate Limits
Default Limits
Rate limits are configurable per deployment. The values above are defaults. Always check the X-RateLimit-* response headers for your current limits.
All responses include rate limit headers so you can track your usage programmatically.
Handling Rate Limits
When rate limited, the API returns 429 Too Many Requests with a Retry-After header:
Implement exponential backoff to handle rate limits gracefully:
Always respect Retry-After headers when present. Ignoring rate limits may result in your API key being temporarily suspended.
List endpoints use cursor-based pagination. Each response includes a next URL that you follow to retrieve the next page of results.
Query Parameters
Best Practices
Respect Rate Limits
- Check
X-RateLimit-Remaining before making bursts of requests
- Implement exponential backoff with jitter when limits are reached
- Spread requests over time for bulk operations instead of sending them all at once
- Use the
next URL directly rather than constructing cursor values manually
- Process results as you paginate instead of loading everything into memory
- Set a reasonable
limit parameter to balance between fewer requests and smaller payloads
Caching
- Cache responses for resources that change infrequently (e.g., dataset metadata, project configurations)
- Use the
updated_at timestamp to determine when cached data is stale
- Avoid caching paginated list responses since the underlying data may change between requests
Concurrent Requests
- Stay within concurrent connection limits for uploads (10) and exports (5)
- Use a semaphore or connection pool to manage concurrent requests in your application
- Queue requests that exceed concurrency limits rather than dropping them