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

# Error Handling

> Understand request validation errors and API business-rule failures

# Error Handling

WazzAPI uses standard HTTP status codes, but the exact JSON body can vary depending on the type of failure.

## Error Format

Validation errors usually use a `detail` array format:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

Application-rule failures usually return a simpler payload:

```json theme={null}
{
  "detail": "Message limit exceeded for your plan."
}
```

## Common Error Codes

| Code                        | Status | Description                                                                        |
| :-------------------------- | :----- | :--------------------------------------------------------------------------------- |
| `422 Unprocessable Entity`  | 422    | Request validation failed before the request could be processed.                   |
| `401 Unauthorized`          | 401    | Missing or invalid API key.                                                        |
| `404 Not Found`             | 404    | The requested message, contact, template, or group does not exist.                 |
| `409 Conflict`              | 409    | A duplicate resource already exists, such as a contact with the same phone number. |
| `429 Too Many Requests`     | 429    | Request throttling or plan-based feature usage limit exceeded.                     |
| `500 Internal Server Error` | 500    | Unexpected server-side failure.                                                    |

## Handling Specific Errors

### Validation Errors (`422`)

Field-level details are returned when the request body or query parameters are invalid.

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "whatsapp_account_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

### Account Disconnected (`400`)

If the WhatsApp account is disconnected or unavailable:

```json theme={null}
{
  "detail": "WhatsApp account is not connected"
}
```

**What to do:** Reconnect the device in **Devices**, or listen for `device.disconnected` on your [webhook](/webhooks) and reconnect before sending again.

### Proxy change while connected (`409`)

You cannot change proxy settings while the device is still connected:

```json theme={null}
{
  "detail": "Disconnect this account before changing proxy settings."
}
```

**What to do:** Disconnect the device, update the proxy, then reconnect. See [Proxy Support](/features/proxy).

### Invalid proxy URL (`400`)

```json theme={null}
{
  "detail": "Only HTTP and SOCKS5 proxies are supported."
}
```

**What to do:** Use `http://host:port` or `socks5://user:pass@host:port`. HTTP proxies need an explicit port.