Reference
Rate limits and pagination
The call limits, the size limits, the list paging rules and the idempotency header, as the code sets them.
This page lists the limits that can refuse or shorten a call.
Throttle scopes#
A throttle counts calls in a time window and answers 429 when a caller is over the limit. Each scope has its own counter. The counter is per signed-in account. A caller who is not signed in is counted by network address.
| Scope | Limit | Endpoints |
|---|---|---|
login | 10 a minute | POST /auth/login/, POST /auth/invite/accept/, POST /auth/password/reset/ |
login_name | 5 a minute | POST /auth/login/, counted per username and network address |
login_account | 20 an hour | POST /auth/login/, counted per username from any address |
password | 10 an hour | POST /auth/password/ |
decision | 60 a minute | Hold decision, bulk decision, appeal decision, approval decision, application decision |
ingest | 30 an hour | POST /ingest/feed/, POST /ingest/connect/, POST /scoring/runs/ |
hook | 120 a minute | The trust pages (/trust/status/, /trust/controls/, /trust/incidents/) |
assistant | 40 a minute | POST /assistant/chat/ |
assistant_act | 30 a minute | POST /assistant/act/ |
mcp | 120 a minute | POST /mcp/ (the MCP endpoint for Claude and Codex) |
A request that is over a limit gets 429, the header Retry-After (seconds to wait) and this body:
{ "code": "error", "message": "Request was throttled. Expected available in 30 seconds.", "fields": null }API key limits#
A key has two more limits. They apply only to calls made with a bearer key.
| Limit | Value | When over |
|---|---|---|
| Per key, per minute | rate_per_minute on the key, 1 to 6000, default 120 | 429 and Retry-After with the seconds left in the current minute |
| Per organization, per day | daily_api_calls in the plan, default 50,000. A value of 0 means no limit. | 429 and Retry-After: 3600 |
The daily count uses the Riyadh calendar day. When a measure passes 80 percent of its plan limit, Yaqeen sends one alert a day to the alert channels, if any are set up. An admin can lower the limits with PUT /api/v1/usage/plan/. Raising one past the plan needs us.
Size limits#
| Limit | Value | Error |
|---|---|---|
Rows in one POST /ingest/feed/ or POST /ingest/connect/ call | 5,000 | 400, with rows in fields |
| Zip upload | 300 MB | 413 too_large |
| Any other request body sent through the site's address | 10 MB | 413 from the proxy, as an HTML page, not JSON |
| Holds in one bulk decision | 50 | 400 with the field name in fields |
| Appeal file | 1 byte to 10 MB, PDF, JPEG or PNG | 400 bad_size, 400 bad_type |
| Files on one appeal | 5 | 409 too_many_documents |
| Audit export range | 92 days, at most 20,000 rows | 400 bad_range |
Scoring recent_days | 1 to 60, default 7 | 400 |
| Active webhook endpoints | 5 | 409 too_many |
| Saved views per person | 30 | 409 too_many_views |
| Assistant message | 2,000 characters | 400 too_long |
| One MCP message | 64 KB | 413 too_large |
Sign-in limits for Claude and Codex#
The OAuth endpoints under /api/v1/oauth/ have their own counters, kept per network address: 60 a minute for the sign-in page and for token requests, 10 an hour for client registration and 60 a minute for revoking. The password step on the sign-in page also allows 8 tries in 15 minutes per username. Over a limit, the token and register endpoints answer 429 with slow_down.
Pagination#
List endpoints that can be long use limit and offset paging. Send limit and offset as query parameters.
| Parameter | Default | Rule |
|---|---|---|
limit | 25 | The most rows to return. A value above 100 is cut to 100. A value that is not a positive whole number is ignored and the default is used. |
offset | 0 | How many rows to skip. A bad value is ignored and 0 is used. |
The response has this shape:
{ "count": 83, "next": "https://api.example.test/api/v1/holds/?limit=25&offset=25", "previous": null, "results": [] }count is the total number of rows that match. next and previous are full addresses, or null at the ends. Follow next until it is null.
curl "https://api.example.test/api/v1/holds/?status=approved&limit=100&offset=0" \
-H "Authorization: Bearer yq_live_..."These endpoints are paged:
- Holds and stores:
/holds/,/holds/{id}/orders/,/stores/,/owners/,/payouts/ - Review work:
/cases/,/cases/{id}/notes/,/cases/{id}/outcome/,/approvals/,/intake/,/suppressions/,/reserves/,/reserves/disputes/ - Records:
/audit/,/privacy/requests/,/users/,/jobs/,/ops/errors/ - Other:
/webhooks/{id}/deliveries/,/notifications/,/assistant/chats/
Other list endpoints, such as /keys/, /webhooks/, /rules/ and /views/, return the whole list as a plain array.
Idempotency#
The Idempotency-Key header works on POST /holds/{id}/decision/ and POST /holds/bulk-decision/ only. The key is 8 to 128 letters, digits, - or _. Yaqeen keeps the first answer for 24 hours. The same key with the same body returns that answer with Idempotent-Replayed: true. The same key with a different body gets 422 idempotency_key_reused. A second request while the first is running gets 409 in_progress. Read Safe retries for the steps.
Related#
- Handle errors: what to do after a
429. - Authentication: set the limit when you create a key.
- Safe retries: the idempotency header in use.
- Errors: every error code.