> ## Documentation Index
> Fetch the complete documentation index at: https://docs.technified.xyz/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](/developer-api/rate-limits)     |
| `500` | Server error | Something failed on our side. Safe to retry with backoff                         |

## Recovering from each

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

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

## 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"
}
```