API errors and retries

When a request fails, the HTTP status tells you why, and the body usually adds a message. This page explains the common statuses and when it is safe to retry.

What each status means

Status	Usual meaning
400	The request is not in the form this endpoint expects, for example a wrong format or an empty file.
401	Your credential is missing, invalid or expired, or a sign-in or MFA token was rejected.
403	Your role, project membership or API key scope does not allow the request, or a policy refused it.
404	The item does not exist or you cannot access it. An expired upload status also returns 404.
409	The request clashes with the current state. For example, someone changed the item first, it is a duplicate, the same operation is already running, or sharing a report was refused.
413	The upload, form or archive is too large.
422	The request failed validation.
429	You sent too many requests, or sign-in is locked after too many failed attempts.
503	A service that TestLookup needs, such as storage or an AI provider, is unavailable. Or the server is not taking more work right now, or the feature is turned off on this installation.

An endpoint’s own page can add details. In the API specification, 730 of the 731 operations list only success statuses and 422, and none lists 401 or 403. So expect these statuses even where a page does not list them.

Error response body

Most errors return a JSON object with a detail member:

• Usually detail is a message, for example {"detail": "Test run not found"}.
• A 422 validation error returns a list in detail, one entry per problem. Each entry has loc (where the problem is, such as ["query", "days"]), msg (what is wrong) and type.
• Some endpoints put an object in detail, for example with a message and a reason.

Read the status first, then detail.

SCIM errors

SCIM endpoints (/api/v1/scim/v2/*) return SCIM error objects instead of {"detail": …}. Their schemas list contains urn:ietf:params:scim:api:messages:2.0:Error.

When to retry after 429 or 503

• 429: wait the number of seconds in the Retry-After header, then retry.
• 503: the cause is often temporary. Storage, an AI provider or the list of revoked sign-ins may be unavailable, or the server may be busy. Some busy responses also include Retry-After, so wait that long when it is there. If a 503 keeps coming back, the feature may be turned off on this installation, or a service it needs may be down.

Retrying a POST

Do not repeat a POST automatically after it failed or timed out, because the first attempt may already have worked. Repeat it only if the endpoint accepts a key that makes a repeat safe. For example, POST /api/v1/agents/{agent_id}/invoke accepts an Idempotency-Key header. If you send the same key with the same request, it returns the invocation it already created instead of starting a new one.

Empty, file and stream responses

• 46 endpoints return no body on success (204).
• File downloads and event streams do not return JSON. Check the content type in the endpoint’s Responses table.
• Endpoints with undocumented responses return JSON, but the API specification does not list their fields.

More detail is in the source repository on GitHub: the API guide.