Docs · Error codes
API error codes.
Every Guest Talk API error carries a stable machine-readable code alongside a human-friendly message. This page enumerates the codes, their HTTP statuses, what they mean, and the action a well-behaved client should take.
| Code | HTTP | Meaning and fix |
|---|---|---|
| unauthenticated | 401 | No or invalid Authorization header. Fix: pass a valid API key or OAuth token. |
| unauthorized | 403 | The credential is valid but lacks permission for the requested resource or operation. Fix: check role and scope. |
| workspace_suspended | 403 | The workspace is suspended for non-payment or AUP breach. Fix: contact billing. |
| not_found | 404 | The referenced object does not exist or is not visible to the caller. Fix: check the ID. |
| conflict | 409 | The request conflicts with the current state of the target resource. Fix: reload and retry, or re-check preconditions. |
| validation_error | 422 | The request body failed schema validation. Fix: inspect the detailed field errors in the response. |
| invalid_state_transition | 422 | The requested state change is not allowed from the current state (e.g. cancel a completed reservation). |
| rate_limit_exceeded | 429 | Too many requests. Fix: back off per Retry-After header. |
| internal_error | 500 | Unexpected error. Fix: retry with exponential backoff; if persistent contact support with the request ID. |
| service_unavailable | 503 | Guest Talk is briefly unavailable. Fix: back off and retry; check the status page. |
| channel_declined | 422 | An OTA declined the mutation (e.g. rate below floor). Fix: adjust the value and retry. |
| payment_declined | 422 | The payment processor declined the charge. Fix: use a different payment method. |
| duplicate_idempotency_key | 409 | An earlier request with the same idempotency key exists with a different body. Fix: use a new key. |
| webhook_verification_failed | 400 | The webhook consumer failed its handshake. Fix: implement the signature check correctly. |
| template_not_approved | 422 | A messaging template is not approved by Meta (or equivalent). Fix: submit for approval or use an approved template. |
Error body envelope
{
"error": {
"code": "validation_error",
"message": "arrival_date must be before departure_date",
"docs_url": "https://talkg.fabriza.org/docs/error-codes#validation_error",
"request_id": "req_01H8XY5ZK4Q2R7P9",
"details": [
{ "field": "arrival_date", "reason": "after_departure" }
]
} }
Always log the request_id; it lets Guest Talk support trace the request across our infrastructure in seconds. Never surface the raw message to end users; use it in logs only, and present a friendly translation to your own users.
New codes
Guest Talk adds new codes for new failure modes over time. Clients should treat unknown codes as generic errors of the same HTTP class rather than crashing; the human message and the details field will always be present.