Getting started
Responses and errors
Every response, success or failure, has the same envelope. HTTP status codes are real: check the status first, then read error.code.
The envelope
Every response is JSON with ok, a request_id and time_ms. A success adds cost (the checks the call used) and result. A failure adds error with a machine-readable code and a human message. The same id is sent in the x-request-id header: quote it if you contact us.
Some errors carry extra fields inside error: quota_exceeded includes a quota object, and project_limit includes limit and used.
Status and error codes
| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_request, invalid_domain, invalid_prompts, invalid_days, invalid_ip | Fix the request; the message says what. |
| 401 | unauthorized | Missing, malformed, unknown or revoked key. |
| 402 | quota_exceeded, project_limit | The workspace is out of checks or projects for its plan. |
| 403 | forbidden, plan_required | The key can no longer act for its workspace, or the endpoint needs a paid plan. |
| 404 | not_found | No such project in the key’s workspace, or no such endpoint. |
| 405 | method_not_allowed | The endpoint does not take that HTTP method. |
| 429 | rate_limited, monthly_limit | 120 calls a minute per key; 30 a minute per IP without one. monthly_limit means the plan’s API requests for the month are used. |
| 500 | server_error | Our side. Retry with backoff; quote the request_id if it persists. |
Unknown paths under /api/v1 answer 404 not_found and a wrong method answers 405 method_not_allowed, both in the same envelope rather than an HTML page. Each endpoint page lists the errors that endpoint can return.
Retrying
Do not retry 400, 401, 402, 403 or 404: the request has to change first. Retry 500 with backoff. For 429, wait for the retry-after header; see rate limits.