Errors, retries, and side effects

Common error body

Every Agent API error uses one envelope. Branch on error.code, never English text. Keep error.requestId for support and observability. retryable=true means a bounded retry may be appropriate; the transaction rules below still take precedence.

{
  "error": {
    "code": "payment_not_authorized",
    "message": "Payment must be authorized before confirming the booking",
    "status": 400,
    "requestId": "req_...",
    "retryable": false,
    "details": []
  }
}

Stable error codes

The message below is representative and useful for debugging; branch only on error.code. retryable is the value in the error envelope, not permission to repeat a write without the recovery rule.

What to do by status

Operation safety matrix

Idempotency rules

• Create checkout, confirm, and cancel require an Idempotency-Key whose trimmed length is at least eight characters. That is the current published input constraint; no maximum length or restricted character set is established. For portability, use a conservative ASCII UUID-like token with no leading or trailing whitespace, and retain its exact bytes.
• An idempotency key identifies one logical write; it does not make a replay safe. Follow the operation-specific recovery rule below.
• Submit Create checkout serially and retain the exact serialized request body before the first attempt. The key alone is not permission to send a second request.
• A Quote can own exactly one checkout. A different logical create for that Quote returns 409 quote_checkout_conflict. Read the typed details[].checkoutSessionId and matching details[].nextAction.type=get_checkout, then retrieve that checkout. Never parse the human reason text. If the typed identifier is absent, stop or obtain a fresh Quote before creating another checkout.
• Only after an ambiguous transport result or HTTP 502, 503, or 504 may trusted code recover Create checkout with the same key and the byte-identical retained body. A changed body returns 409 idempotency_conflict. v1 does not return a replay header; compare the checkout identifier and retrieve current state.
• There is no universal replay-retention promise. Lookup scope and recovery lifetime depend on the Quote, checkout session, booking, and operation. Key rotation inside the same application does not bypass those rules. Do not rely on replay after a checkout expires.
• After an indeterminate Confirm response or typed confirmation 409, make only GET requests for the original checkout. Never issue another booking write, even with the same key.
• When checkout status is expiry_requires_attention, follow expiration.nextAction. Do not Confirm or create another checkout from the same Quote. Only payment.status=voided together with expiration.phase=voided proves the hold was released.
• Once Cancel is submitted, use GET booking only while its outcome is pending or unknown. Never resubmit it, even with the same key.
• Cancellation has a stricter recovery rule. When the booking is cancellation_in_progress, GET-poll the existing booking and do not call Cancel again—even with the same key. When it is cancellation_requires_attention, or when cancellation.outcome=unknown, stop all cancellation writes and contact support.
• There is no published timeout after which a cancellation becomes safe to resubmit. If an in-progress state does not change, treat it as stale and escalate with the redacted booking reference and request ID.
• Only an error explicitly documented as occurring before supplier cancellation may start a new Cancel attempt. Create a fresh preview, present the current consequences, and obtain fresh human approval first; if the operation-specific error says to stop, stop.