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).
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.

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.

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.