RELIABILITY
Errors & retries
Errors include a safe code and request ID. Never log API keys, prompts, or tool content while diagnosing a failure.
| Status | Meaning |
|---|---|
| 400 / 422 | Invalid fields, capabilities, or routing constraints |
| 401 / 403 | Invalid credentials or insufficient access |
| 402 | Insufficient available prepaid funds |
| 409 | Idempotency conflict, in progress, or already completed |
| 429 | Too many attempts |
| 503 | Service, storage, or model release unavailable |
Idempotency
Send a stable Idempotency-Key for one logical operation. It is scoped to the project and protocol. Reusing it with a different payload fails with 409. A matching duplicate currently returns 409 with the original request and receipt location; encrypted response replay remains pending implementation.
Ambiguous outcomes
After a timeout, inspect the original receipt. Do not generate a new idempotency key merely to discover whether a request executed. A retry with a new key can represent another billable request.
Execution and billing
A completed response can still have pending billing when financial evidence is unknown or delayed. The receipt is authoritative; pending does not mean free.