Errors

Status codes

Failures use standard HTTP status codes. The response body carries a message describing the cause.

Status	Meaning	Retry?
400	The request body failed validation. The message names the offending field.	No — fix the request first.
401	Missing or unrecognised token.	No.
403	Token inactive, expired, or missing the required permission.	No.
404	No such record in your organization.	No.
409	Conflicts with current state — e.g. sending outside the 24-hour window, or starting a session that already exists.	Only after resolving the conflict.
429	Rate limit exceeded.	Yes, after the reset time.
500	Server error.	Yes, with backoff.

404 and organization scoping

Every id is scoped to the organization the token belongs to. Passing a valid id that belongs to a different organization returns 404, not 403 — the record genuinely does not exist as far as your token is concerned. This is intentional: a 403 would confirm that the id exists somewhere, which leaks information across organizations.

Retrying safely

Retry 429 and 500 with exponential backoff. Do not blind-retry 4xx responses other than 429 — the request will fail identically and you will spend rate-limit budget doing it.

Message sends are not idempotent. There is no idempotency key today, so a retry after a timeout can deliver the message twice. If a send times out, read the chat's recent messages before retrying rather than sending again blind.