Limits, errors & retries
Keep requests efficient, recover safely and know when to stop.
Request allowances
These counters are shared across application servers. Creating extra keys does not bypass the account limit. Requests denied by a scope or validation check still consume the admitted allowance. Rate-limited requests appear in usage but do not consume another admission.
Separate limits still apply to uploads, saved papers, PDF preparation and automated marking. A key grants permission; it does not add account allowance. The API exposes X-RateLimit-Remaining and X-RateLimit-Daily-Remaining, accounting for both key and account quotas.
| Limit | Per key | Across your account |
|---|---|---|
| All requests per minute | 120 | 300 |
| Accepted requests per UTC day | 10,000 | 20,000 |
| Write requests per minute | 20 | 40 |
Read the error
Keep X-Request-Id when investigating a failed request. Private resource IDs belonging to another user do not grant access.
{
"error": {
"code": "insufficient_scope",
"message": "This API key does not have all the permissions required for this operation.",
"requiredScopes": ["papers:write"]
},
"requestId": "<request UUID>"
}| Status | Action |
|---|---|
| 401 | Supply a valid, unexpired, unrevoked key for a verified account. |
| 403 | Check required scopes and account restrictions. Do not repeatedly retry. |
| 404 | Check the path and owner-scoped resource ID. |
| 409 | Inspect the existing resource or revision before retrying. |
| 413 / 415 | Reduce the payload or send the expected content type. |
| 422 | Correct the fields reported in error.details. |
| 429 | Wait for Retry-After, then retry within the account’s limits. |
| 503 | Service is unavailable or disabled. Back off; keep the same operation IDs. |
Retry without duplicating work
- Use a stable Idempotency-Key for session creation, Builder-to-marking imports, starting marking, question requests and external import completion. A different operation needs a different key.
- For paper creation, keep the client-generated UUID and exact body. For paper updates and reviews, use the returned current revision; a stale revision conflicts.
- A file upload can succeed even if its response is lost. Check the session’s assets before repeating it.
- Retry reads, identical creations and export preparation after transient errors with bounded exponential backoff. Honour Retry-After. Stop after a few attempts and report the saved resource ID so work can be resumed.
Versioning and discovery
Public routes live under v1. Clients should tolerate additional response fields, and should use the published schemas for strict request bodies. A schema version identifies imported marking independently of the API path version.
Read openapi.json for machine-readable operations and llms-full.txt for the plain-text guides. Keys and account management use the signed-in Wingman app; API credentials never authenticate those pages.