# Errors and client recovery

Availability: **Proposed specification**  
Documentation: **1.1** | Updated: **19 September 2026**

[Documentation home](../README.md)

Use a stable machine-readable error code and a human-readable explanation. The proposed error envelope follows RFC 9457 Problem Details, with error_code and request_id extensions. Details must be sanitized and must not reveal another tenant's objects. [S3](https://www.rfc-editor.org/rfc/rfc9457.html)

| HTTP status | Condition | Client action |
| --- | --- | --- |
| 400 | Malformed encoding, JSON or duplicate member names | Correct the request |
| 422 | Well-formed request violates a supported contract | Inspect the field error and revise the input |
| 401 | Missing or invalid authentication | Obtain valid credentials through the supported flow |
| 403 | Authenticated caller lacks permission | Request the required scope |
| 404 | Object absent or not visible to this caller | Check the identifier without inferring tenant existence |
| 409 | Idempotency conflict, stale generation or invalid transition | Read authoritative state; resolve the conflict |
| 429 | Rate limit exceeded | Honor Retry-After and use bounded backoff |
| 503 | Temporary service or capacity unavailability | Retry only within the task and budget policy |

## Illustrative error object

```json
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "The idempotency key is bound to another request.",
  "error_code": "IDEMPOTENCY_CONFLICT",
  "request_id": "illustrative-request-id"
}
```

This object illustrates the draft format. Network error codes remain subject to contract approval. The local CLI error strings in the troubleshooting chapter are a separate reference interface.

## Recovery without duplicate effects

A timeout does not show whether the server committed a request. Recover with the original idempotency key or recorded task identifier. Retry delays should include jitter and a ceiling; a 429 or 503 response does not authorize exceeding a deadline or creating a second payment.

Preserve the request identifier and sanitized diagnostic context when escalating an error.

[Previous](./api-design.md) | [Next](./identity.md)