Rate limits
The per-endpoint RobinReturn Partner API rate limits, the X-RateLimit headers on every response, and how to back off after a 429.
Last updated
Limits are per company and per endpoint: each endpoint has its own counter, so uploading invoices never uses up the quota for creating cases. Every window is a fixed 60 seconds.
| Endpoint | Limit |
|---|---|
POST /api/v1/uploads | 300 requests per 60 seconds |
POST /api/v1/cases | 60 requests per 60 seconds |
GET /api/v1/cases/{id} | 120 requests per 60 seconds |
Rate-limit headers
Every response to a request the limiter counted — a success, or an error the endpoint itself returns — carries your quota for that endpoint:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57The headers are not sent on a 401 or 403, on a 400, 413 or 422 from reading the body,
or on a 500: those are refused before the request is counted, or say only that something broke.
Pace yourself on X-RateLimit-Remaining rather than waiting to be refused.
Backing off
When a counter is used up, the request is refused with 429 and a Retry-After header — the
number of seconds until that endpoint's window resets. The body carries the same figure:
{ "error": "Rate limit exceeded", "retryAfterSeconds": 42 }- Wait at least
Retry-Afterseconds before calling that endpoint again. The other endpoints are not affected. - Prefer batching:
POST /api/v1/casesaccepts up to 100 cases per request. - Retry a case batch under the same
Idempotency-Key. Within the replay window the retry returns the original answer rather than running the batch again — see Idempotency.
Idempotency
How the Idempotency-Key header replays a Partner API batch on retry, when you get 409 or 422 instead, and how the per-invoice duplicate guard catches unkeyed retries.
Errors
The RobinReturn Partner API error model, HTTP statuses, and the per-case rejection codes returned when creating cases.