Skip to content

Error Handling

Every error response follows a consistent JSON shape. Use the error field to branch your logic.

Response Shape #

All error responses return a JSON object with two fields:

Field Type
error string
message string | null

The error field is always present and is a machine-readable snake_case code. The message field is optional and may contain a human-readable explanation. 

{
  "error": "not_a_member",
  "message": "Bot is not a member of this space."
}

HTTP Status Codes #

Status Meaning
200 Success. Response body contains the result.
400 Bad request — invalid input, validation failure, or precondition not met.
401 Unauthorized — missing, invalid, or expired bot token.
403 Forbidden — bot lacks the required permission or verification status.
404 Not found — the resource does not exist or is not accessible.
409 Conflict — resource already exists (e.g. bot already installed).
413 Payload too large — the request, or a file in it, is over the size limit.
422 Unprocessable — the request is well-formed but refused: a limit is reached or moderation rejected a file.
429 Rate limited — too many requests. Back off and retry after the indicated period.
500 Internal server error — something went wrong on our end. Retry with backoff.
503 Service unavailable — the server cannot do this particular work right now (see render_unavailable). Nothing was changed; retry later.

Common Error Codes #

These error codes appear across multiple endpoints. Each API reference page lists the specific errors that endpoint can return.

Code Description
not_a_member Bot is not a member of the target space. The space membership filter blocked the request.
not_verified Endpoint requires a verified bot. Apply for verification through the Developer Console.
not_found The requested resource (channel, command, member, etc.) does not exist.
channel_not_found The specified channel does not exist in the target space.
not_voice_channel The channel exists but is not a voice channel. Voice operations require voice-type channels.
insufficient_permissions The bot's role in the space lacks the permission the endpoint needs, or the object is not the bot's to change.
invalid_request A multipart form could not be read: a required field is missing or malformed, or an attach:// reference names no part of the request.
too_large 413 — the request, or a file in it, is over the size limit.
rate_limited 429 — the bot's window for this interface is empty. Wait Retry-After seconds; the body also carries retry_after.

Sticker & Emoji Error Codes #

Returned by IExpressions and IFiles. What each means for a bot is in Stickers & Custom Emoji → Errors.

Status Code Description
400 invalid_format A title, slug, name, emoji or keyword is not acceptable, or the file is not (format, dimensions, duration, frame rate, Lottie features).
409 name_taken The pack slug or the emoji name is already used in the space.
413 too_large The request is over its limit (5 MiB for AddItem), or the file over the size its format allows.
422 quota_exceeded The space's packs or item slots, the pack, or the bot's 100 unused uploads are full.
422 content_rejected Moderation refused the file. Sending it again gets the same answer.
429 space_rate_limited The bots' budget for sticker and emoji changes in this space is spent for the minute. Retry-After: 60. See Rate Limits.
503 render_unavailable AddItem with an animated file: the server cannot render it right now. Nothing was added; send the same request again later.

Attachment & Reaction Error Codes #

Returned by IMessages/Send with attachments and by IFiles/Upload (see Files & Attachments), and by IReactions/AddCustom (see Reactions).

Status Code Description
400 validation_error The message is not valid for the channel — among other things, more than 10 attachments.
400 invalid_format An attached or uploaded file is empty.
400 invalid_request The body could not be read, an attach:// names no part, or an attach:// is in a JSON body.
403 insufficient_permissions Send: no AttachFiles in the channel. AddCustom: no AddReactions, or an emoji of another space and the bot is not verified.
404 not_found Send: a fileId names no attachment upload of the bot — unknown, over 24 hours old, or uploaded for a sticker or emoji. AddCustom: the emoji does not exist or was deleted.
413 too_large A file is over 10 MiB, or the request carries more than about 10 MiB of parts.

Best Practices #

Match on error, not message — the message text may change between versions. The error code is part of the stable contract.

Handle unknown error codes gracefully — new codes may be introduced in future versions. Fall back to the HTTP status code for unrecognized errors.

429 responses include rate limit info — check Retry-After header for how long to wait before retrying. See Rate Limits for details.