Errors and retries
Interpret API errors and retry saved payloads without changing their identity.
API errors return a JSON object with a machine-readable error and a requestId:
{
"error": "invalid_api_key",
"requestId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
}Keep the request ID when diagnosing a failure. Error responses also include X-Request-ID and Cache-Control: no-store.
| Status | Examples | Action |
|---|---|---|
| 400 | invalid_json, invalid_envelope, invalid_query, invalid_request, invalid_evaluation | Correct request shape, headers, or filters |
| 401 | invalid_api_key | Supply a valid key |
| 403 | insufficient_key_access | Use the operation's read or write access |
| 404 | trace_not_found, not_found | Check the ID and credential scope |
| 409 | trace_conflict, evaluation_conflict | Use original bytes for a retry; use a new identity for a new result |
| 413 | payload_too_large | Keep uploads within 4 MiB |
| 415 | unsupported_media_type | Send Content-Type: application/json |
| 500 / 503 | internal_error, ingest_unavailable, read_unavailable | Retry after a delay |
Endpoint pages list their relevant behavior. An HTTP status from infrastructure may arrive without this JSON body; check the status before decoding a success response.
Retry policy
Use bounded backoff for network failures, HTTP 408, 425, 429, and 5xx responses. Preserve trace IDs, native evaluation result IDs, and saved bytes across attempts. Do not repeatedly resend permanent validation or access failures without fixing their cause.
The Swift trace outbox retries during later upload activity and explicit flushes. The evaluation reporter attempts delivery up to three times and retains unsuccessful files for retryPending. See delivery and troubleshooting.