API reference
Errors
Every error the API returns, its shape, and what to do.
{
"error": "service_unavailable",
"detail": "Agent Lens is temporarily offline. This run was not counted; please try again in a few minutes.",
"request_id": "req_3f1c0a9b2e7d",
"service": "agent-lens"
}
error: a stable code to branch on.detail: a sentence for people; it may change.- Agent Lens never returns a partial
allow. If a read does not complete, the call fails, and your code applies its fail mode.
| Status | error | Meaning | What to do |
|---|---|---|---|
| 401 | missing_key | no key sent | send Authorization: Bearer or X-API-Key |
| 401 | invalid_key | unknown, disabled or expired key | check the key at Profile → API keys |
| 404 | unknown_product / unknown_endpoint | wrong path | see Authentication for the paths |
| 422 | bad_request | invalid body (detail names the field), e.g. Agent Lens without an answer or a tool_call | fix the request |
| 429 | rate_limited | more than 10 requests a minute | wait Retry-After seconds |
| 429 | daily_limit | today's 10 runs for this product are used | wait for resets_at (00:00 UTC), or ask for more |
| 503 | busy | Agent Lens: the GPU queue is full | retry in a few seconds |
| 503 | scoring_unavailable | Agent Lens: the read did not complete | retry, or apply your fail mode |
| 503 | service_unavailable | the product is offline, or the Integrity scanner is waking up | retry in a minute |
| 504 | timeout | the run took too long | retry; for Integrity, a first scan of a large model can take minutes |
Retrying
Retry 429 rate_limited after Retry-After, and 503 / 504 with a growing delay (for example 5 s, 15 s, 60 s).
Do not retry 4xx otherwise: the same request gets the same answer.