Errors

Errors use the same envelope as successful responses, with an optional details object.

{
  "status": "error",
  "code": 401,
  "message": "Invalid API key for this guild",
  "details": { "code": "NOT_FOUND" }
}

Always branch on the HTTP status code, not the message text. Messages may change.

Status codes

Code	Meaning	Common cause
`200`	Success	The request worked
`400`	Bad request	Missing a required field, a batch over its size limit, or an already-banned user
`401`	Unauthorized	Missing API key, or a key that is invalid or revoked
`403`	Forbidden	The key’s guild does not match the guild you are targeting
`404`	Not found	The user is not verified in the guild, or no active ban or mute exists
`429`	Rate limited	You exceeded a category quota. See Rate Limits
`500`	Server error	Something failed on our side. Safe to retry with backoff

Recovering from each

401 Unauthorized

Check the key is sent in one of the accepted headers and copied in full. If it was revoked in the dashboard, create a new one under Settings > API Keys.

403 Forbidden

Your key is bound to one guild. Make sure the :guildId in the path (or the X-Guild-ID header) matches the guild the key was created for.

404 Not found

For lookups, the user is not verified in that guild. For unban or unmute, there is no active punishment to lift. Neither is necessarily an error in your code.

429 Rate limited

Wait for the number of seconds in the Retry-After header, then retry. Cache and batch to avoid hitting the limit again.

500 Server error

Retry with exponential backoff. If it persists, report it in the support server.

Validation errors

A 400 from a write endpoint usually names the missing or invalid field in message, for example:

{
  "status": "error",
  "code": 400,
  "message": "Missing required field: reason"
}

Developer API

Endpoints

Playground

Reference

Status codes

Recovering from each

Validation errors

​Status codes

​Recovering from each

​Validation errors

Status codes

Recovering from each

Validation errors