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]
Swipe or scroll to view all columns →
| 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#
{
"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.