Errors

When a request fails, the API answers with an HTTP status that matches the problem and a body with the same shape every time.

{
  "message": "The request was refused as invalid",
  "code": "INVALID",
  "details": { "fields": ["messages.0.text"] }
}

Field	Description
message	An English explanation for developers. The wording may change, so don’t make decisions in code based on it.
code	A constant that doesn’t change. Base your code’s decisions on this.
details	Only for some codes, e.g. fields, retry_after, reason, until

Every answer has an X-Request-Id header. Include it when you report a problem to us. Answers never contain stack traces or messages from internal systems.

Codes

Requests and authentication

HTTP	code	Meaning
400	INVALID_JSON	The body isn’t exactly one JSON object
400	BAD_REQUEST	A malformed request
401	INVALID_TOKEN	Missing or invalid token
403	BOT_DISABLED	The bot is switched off
404	NOT_FOUND	No such path or resource
404	UNKNOWN_VERSION	No such version in the path (use /v1)
405	METHOD_NOT_ALLOWED	The path doesn’t take this method
408	REQUEST_TIMEOUT	The request was sent too slowly
413	BODY_TOO_LARGE	The body is over 64 KB
415	UNSUPPORTED_MEDIA_TYPE	Content-Type: application/json is missing
422	UNKNOWN_FIELD	The body has a field the endpoint doesn’t take
422	INVALID	A value failed validation; details.fields names the fields or details.reason the cause
429	RATE_LIMITED	Too many requests; see Retry-After
431	HEADERS_TOO_LARGE	The HTTP headers are too large

Messages, chats and webhooks

HTTP	code	Meaning
400	REPLY_TOKEN_INVALID	The reply token is unknown, used, expired, another bot’s or another chat’s
403	FORBIDDEN	The bot may not do that; details.reason gives the cause: paused, banned (the bot’s status in this chat), attacher_lost_rights, plan_limit, owner_inactive
403	BANNED	The bot is on this room’s ban list
403	CHAT_INACTIVE	The chat isn’t active
403	RESTRICTED	The bot or its owner is restricted (details.until when known)
403	QUOTA_EXCEEDED	The monthly quota is used up
403	EDIT_WINDOW_PASSED	Messages can’t be edited after 48 hours
422	NOT_EDITABLE	This message can’t be edited
422	BANNED_TERM	The text contains a blocked term
422	UNSUPPORTED_MESSAGE_TYPE	A message type that isn’t available yet
422	INVALID_WEBHOOK_URL	The webhook URL can’t be used (details.reason)
429	SLOW_MODE	The chat is in slow mode
4xx	REFUSED	Refused for another reason

Server side (safe to retry)

HTTP	code	Meaning
500	INTERNAL	Something unexpected went wrong
502	UPSTREAM_ERROR	An internal system failed
503	SERVICE_UNAVAILABLE	The bot platform is temporarily unavailable
503	BOTS_DISABLED	Bots are switched off for now
504	UPSTREAM_TIMEOUT	An internal system took too long

When to retry

• 429: wait for Retry-After, then retry.
• 5xx: retry, waiting longer each time (exponential backoff, e.g. 1, 2, 4, 8 seconds) plus a little random extra (jitter). Send a client_id with messages so a retry doesn’t post twice if the first attempt went through.
• Other 4xx: don’t repeat the same request; fix it first.
• v1 may gain new codes, and that doesn’t count as a breaking change (a change that breaks existing code). When your code sees a code it doesn’t know, decide by the HTTP status.