Error codes.

Error envelope

Every non-2xx response from the Guest Talk platform carries the same JSON envelope. The envelope has a stable code, a human-readable message, a request_id that ties the response to the underlying platform log line, and — where relevant — a details array with per-field information. The code is the value your code should branch on; the message is the value you should surface to a human debugging your integration.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "code": "TG-2004",
  "message": "arrival must be strictly before departure",
  "request_id": "req_01HYQ8XN2K9AB4CD",
  "details": [
    { "field": "arrival", "issue": "2026-08-06 is not before departure 2026-08-06" },
    { "field": "departure", "issue": "must be at least one day after arrival" }
  ]
}

Codes are stable across versions within a major API version. Talkguest never repurposes a code for a different meaning; if a new failure mode emerges we mint a new code. This means a client that parses on code instead of message is safe against copywriting changes on our side.

HTTP status conventions

Authentication errors (TG-1xxx)

Auth errors are the first ones every new integration hits. If you are seeing a TG-1001, check the header name spelling first — the platform is strict about the exact string Authorization. If you are seeing a TG-1003, the token is valid but has been scoped read-only or scoped away from the resource you are touching; the fix is on the token, not on the request.

Validation errors (TG-2xxx)

Business logic errors (TG-3xxx)

Business-logic errors are the hardest to design around because they represent a genuine conflict between the request and the state of the property. The pattern that works in production is to treat every 3xxx as an operator-visible signal: surface the code and the message to the operator UI, let them make the decision, then retry with the flag or the adjusted payload they chose.

Integration errors (TG-4xxx)

Rate limit errors (TG-5xxx)

Server errors (TG-9xxx)

Server errors are the ones where the platform itself is at fault. The correct client behaviour on TG-9001 is to retry the same request with backoff — the underlying operation may have succeeded, may have failed, or may not have reached the persistence layer. Idempotency keys on writes make this safe: the retry with the same key either returns the original result or completes the operation for the first time.

Getting help

Every error envelope carries a request_id. When a specific request confuses you, the fastest path to a resolution is a support ticket that quotes the request_id, the endpoint, the payload (with any secrets redacted) and the error code. With the request_id our on-call engineer can go straight to the underlying platform log line without needing to reproduce the call. Without it, we spend the first hour of the ticket asking you to reproduce.

Next steps

Cross-check the resource shapes on the API reference so validation errors go away before they happen. Read the rate limits page so you avoid TG-5001 and TG-5002 in the first place. Read the webhooks page if you would rather subscribe to events than poll and parse errors on the read path. For anything else, reach the integrations team through the contact page or request access.