Rate limiting
GipoNext APIs enforce a limit on the number of requests an application can send within a given time window. This mechanism, called rate limiting, protects service stability for all integrators and clinics.
This page explains how the rate limiter works, which HTTP response it produces, and how to handle it correctly in your code.
How it works
The rate limiter counts requests per OAuth client (identified by client_id) in sliding time windows. When the number of requests exceeds the allowed threshold, excess requests are rejected until the current window ends.
The limit applies to the entire application, regardless of how many users are using your app at once. If multiple users perform operations at the same time, their requests all contribute to the same counter.
HTTP response: 429 Too Many Requests
When you exceed the limit, the server responds with:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please retry after the indicated time."
}Header to read
| Header | Description |
|---|---|
Retry-After | Seconds to wait before retrying the request. Always respect this value. |
⚠️ Always read Retry-After
Do not retry immediately after a 429. The server explicitly tells you how long to wait through the Retry-After header.
Ignoring it and retrying right away causes more 429 responses, worsens the issue, and can prolong throttling.
Why add jitter?
If multiple instances of your application receive a 429 at the same time and all retry after exactly the same number of seconds, the traffic spike repeats. Adding a small random variation (jitter) distributes retries over time and reduces the chance of another collision.
Best practices to avoid hitting the limit
Use refresh tokens instead of requesting new tokens continuously
The token endpoint is rate-limited like every other endpoint. Request a new access token only when the current token expires; do not call the token endpoint on every API request.
Queue batch operations
If you need to process large data volumes (for example patient synchronization), do not send all requests in parallel. Use a queue with a controlled rate (for example N requests per second), so you remain below the threshold.
Avoid aggressive polling
If you need to detect when data changes, avoid aggressive polling by calling the API every minute. Use reasonable intervals, or adopt an on-demand approach (query only when the user requests it).
Behaviour with repeated errors
If you keep receiving 429 responses despite respecting Retry-After, consider that:
- You are running too much parallelism — reduce the number of concurrent requests.
- You have multiple instances of the same application sharing the same
client_id— their requests add up. - You have a bug in your code generating request loops — check for redundant calls or non-terminating loops.
If the issue persists, contact support and include the request volume and the affected endpoint.
Next steps
- OAuth flows and tokens — how to handle token expiration without unnecessary token endpoint calls
- Entities and operations — available resources, scopes, and operational notes