Error Catalog
Error Catalog All error codes with HTTP status, remediation, and recovery actions.
Machine-readable version: GET /.well-known/errors returns this catalog as JSON.
{ "error" : { "code" : "hold_expired" , "message" : "The hold TTL elapsed …" , "detail" : { "hold_id" : "h_01HW…" , "expired_at" : "2026-04-15T19:03:11.000Z" }, "remediation" : "Create a new quote via POST /v1/quotes, then a new hold." , "retry_after" : null , "docs_url" : "https://docs.agenthotel.dev/errors#hold_expired" , "trace_id" : "9f8e…" , "next_actions" : [{ "rel" : "quote" , "method" : "POST" , "href" : "/v1/quotes" }] } } Code Remediation validation_failedInspect detail.field_errors, fix every listed path, retry.
Code Remediation unauthenticatedInclude a valid agent API key or bearer token. delegation_requiredAttach a valid JWT as X-Delegated-User. delegation_invalidCheck detail.reason, retry with fresh token. delegation_issuer_unknownContact tenant admin to register the issuer.
Code Remediation payment_failedVerify token, retry with new token, or surface detail.provider_message.
Code Remediation forbiddenRequest elevated credentials or call within granted scopes. resource_access_deniedAsk admin to grant access to the specific resource. principal_kind_not_allowedRe-authenticate with a credential of the required kind.
Code Thrown by Remediation property_not_foundquotes, properties Search again for valid IDs. room_type_not_foundquotes Call GET /v1/properties/{id}. rate_plan_not_foundquotes Call GET /v1/properties/{id}. quote_not_foundholds Create a fresh quote. hold_not_foundbookings Create new quote + hold. booking_not_foundbookings, cancel Confirm ID and tenant context. oversell_incident_not_foundadmin Refresh oversell queue. agent_not_foundadmin List agents via GET /v1/admin/agents. credential_not_foundadmin List credentials via GET /v1/admin/agents/{id}. booking_authorization_not_foundadmin Create fresh authorization. delegation_issuer_not_foundadmin List issuers via GET /v1/admin/delegation-issuers.
Code Thrown by Remediation idempotency_conflictAny idempotent POST Replay original body or use fresh key. allocation_failedholds Requote; try alternative dates/rooms. allotment_exhaustedholds Try different date or room type. oversell_not_detectedadmin Refresh data before retrying. quote_mismatchbookings Recreate quote → hold → booking chain. hold_not_activebookings Create new quote + hold. booking_not_cancellablecancel Inspect state first. booking_not_modifiablemodify Fall back to staff support. booking_modification_price_changemodify Ask staff or choose same-length dates. authorization_requiredbookings Create authorization first. booking_authorization_invalidbookings Inspect detail.reason, refresh. no_capturable_paymentadmin refund No captured payment. payment_not_refundableadmin refund Only captured/partially_refunded payments. refund_exceeds_remainingadmin refund Reduce to detail.remaining. property_not_promotableadmin Fix detail.reasons pre-conditions. policy_not_found_for_rate_planquotes Contact tenant admin.
Code Remediation quote_expiredCall POST /v1/quotes again. hold_expiredCreate new quote + hold. Room may be unavailable.
Code Remediation rate_limitedBack off for retry_after seconds.
Code Status Remediation internal_error500 Retry with backoff, cite trace_id. payment_provider_error502 Retry with backoff or try alternative payment method. notification_delivery_failed502 Primary operation may have succeeded. Retry notification. payment_timeout504 Provider didn't respond in time — charge may or may not have captured. Retry with the same Idempotency-Key; the provider deduplicates. If timeouts persist, try an alternative payment method.
payment_timeout is thrown by POST /v1/bookings when Stripe, PayPal, or VNPay exceeds the 10-second request budget. Because the outcome is ambiguous, safe recovery requires replay with the original idempotency key — do not generate a new key, which could double-charge.
Code Status Remediation webhook_endpoint_not_found404 List endpoints via GET /v1/admin/webhooks. webhook_delivery_not_found404 Check DLQ via deliveries endpoint. webhook_delivery_not_replayable409 Wait for in-flight delivery to complete.