Skip to main content
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

CodeMeaningCommon cause
200SuccessThe request worked
400Bad requestMissing a required field, a batch over its size limit, or an already-banned user
401UnauthorizedMissing API key, or a key that is invalid or revoked
403ForbiddenThe key’s guild does not match the guild you are targeting
404Not foundThe user is not verified in the guild, or no active ban or mute exists
429Rate limitedYou exceeded a category quota. See Rate Limits
500Server errorSomething failed on our side. Safe to retry with backoff

​
Recovering from each

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.
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.
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.
Wait for the number of seconds in the Retry-After header, then retry. Cache and batch to avoid hitting the limit again.
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"
}