DataForAEOby Advance Labs
Docs menu

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

HTTPcodeWhat to do
400invalid_request, invalid_domain, invalid_prompts, invalid_days, invalid_ipFix the request; the message says what.
401unauthorizedMissing, malformed, unknown or revoked key.
402quota_exceeded, project_limitThe workspace is out of checks or projects for its plan.
403forbidden, plan_requiredThe key can no longer act for its workspace, or the endpoint needs a paid plan.
404not_foundNo such project in the key’s workspace, or no such endpoint.
405method_not_allowedThe endpoint does not take that HTTP method.
429rate_limited, monthly_limit120 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.
500server_errorOur 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.

success · error
{ "ok": true,  "request_id": "…", "time_ms": 12, "cost": { "checks": 0 }, "result": { … } }
{ "ok": false, "request_id": "…", "time_ms": 3,  "error": { "code": "unauthorized", "message": "…" } }