Errors

One error shape for every call, with a code to branch on.

Error shape

Every error has the same shape. message is plain language you can show to a person; branch on code.

ErrorJSON

{
  "error": {
    "code": "conflict",
    "message": "chat is closed"
  }
}

Error codes

HTTP status	code	Meaning
400	`validation`	The request is malformed or a field is invalid. Unknown fields are refused too.
401	`unauthorized`	No token, or the token expired or was revoked.
402	`plan_limit`	The organization reached a limit of its plan.
402	`subscription_locked`	The account is read-only for now.
403	`forbidden`	This caller may not do this.
404	`not_found`	Not found, or not visible to this caller. A record in another organization is always not found.
409	`conflict`	The state changed or a precondition failed.
413	`payload_too_large`	Over the size limit.
429	`rate_limited`	Too many requests. Wait the number of seconds in the Retry-After header.
500	`internal`	Something failed on our side. Retry with backoff.
503	`unavailable`	The service is briefly unavailable. Retry with backoff.

Retries

Retry 429 after the Retry-After seconds, and 500 or 503 with backoff. Don’t retry other 4xx answers unchanged: fix the request first. Each method’s page lists the errors it can answer.