API docs navigation
Errors and Limits
The API returns consistent JSON errors. Plan for auth failures, validation errors, quota and rate limits, and temporary server faults.
Common status codes
- 400: Invalid query or request body.
- 401: Missing or invalid API key.
- 403: Workspace not on a plan with access to the endpoint (for example, API endpoints require Business).
- 404: Resource not found.
- 409: Request conflicts with current state (for example, insufficient stock on preview/replace endpoints, or reaching a quiz's question cap when adding custom questions).
- 429: Rate or daily quota exceeded.
- 500: Unexpected server error.
For POST /api/v1/questions, a 409 means the full requested limit could not be satisfied under the current constraints. The API does not return partial success for that request.
Error payload shape
Typical error body
json{ "error": "Bad Request", "issues": [] }Rate and quota details
- Per-minute throttles return
429 Too Many RequestswithRetry-After. - Daily quota exhaustion returns
429 Quota Exceeded. - The daily quota resets at 00:00 UTC.
- Once a request is authenticated and entitled, downstream endpoint failures can still consume quota budget.
Retry strategy
- Retry
429and5xxwith exponential backoff and jitter. - Treat
409 insufficient_stockas a request-shape issue: lowerlimit, change filters, or retry later after stock refill. - Do not retry
400,401, or403until the input or auth state changes. - Use polling for async resources instead of hot-looping requests.