Rate limits and versioning
API Documentation / API Conventions
Rate limits
Limits apply per application grant and subsidiary. Developer Mode grants begin at 30 requests per minute. Published application grants begin at 120 requests per minute. Finovio administrators may assign another limit.
Every API response includes the current window's limit information:
RateLimit-Limit: 30
RateLimit-Remaining: 18
RateLimit-Reset: 27
RateLimit-Reset is the number of seconds until capacity resets. A limited request returns 429 Too Many Requests and also includes Retry-After in seconds.
Wait for the indicated delay before retrying. Add jitter when several workers share a grant, and avoid retrying all queued requests at once.
Versioning
The major API version appears in the resource path, for example /v1. OAuth endpoints remain unversioned.
Within a major version, Finovio may make backward-compatible changes, including:
- Adding response fields.
- Adding optional request fields.
- Adding resource endpoints and event values.
- Adding enum values where the field is documented as extensible.
- Changing rate limits or token lifetimes communicated through response metadata.
Clients must ignore unknown response fields and handle unknown extensible values without failing the complete response.
Breaking changes require a new major version. Finovio will publish a migration guide and deprecation date before retiring a released major version.
Contract status
The current documentation is a draft contract and may change before v1 is declared available. Once v1 is released, the compatibility rules above apply.