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.