> ## Documentation Index
> Fetch the complete documentation index at: https://technified.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes, the error envelope, and how to recover.

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

```json theme={null}
{
  "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](https://technified.mintlify.site/developer-api/rate-limits.md) |
| `500` | Server error | Something failed on our side. Safe to retry with backoff |

## Recovering from each

> [accordion] 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**.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 500 Server error
>
> Retry with exponential backoff. If it persists, report it in the [support server](https://discord.gg/rPCrq5TwMr).

## Validation errors

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

```json theme={null}
{
  "status": "error",
  "code": 400,
  "message": "Missing required field: reason"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.