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

# API errors

> Understand Wavix API errors: the error formats, what each HTTP status code means, when to retry, and where each channel reports delivery errors.

Wavix reports a problem in one of two ways:

* **Request errors**: the API rejects your request. The response has an HTTP status code of `400` or higher and a body that describes the error. You know right away.
* **Delivery errors**: the API accepts a message, and the message fails later. The request succeeded, so there's no HTTP error. Wavix reports the failure in a webhook. See [Delivery errors](#delivery-errors).

## Request errors

Endpoints return request errors in one of two formats: the [standard error format](#standard-error-format), or the [problem details format](#problem-details-format). The API reference page of each endpoint shows the format it uses.

### Standard error format

Most endpoints, including the SMS and MMS endpoints, return errors in this format.

Errors are JSON with `success` set to `false` and a `message` that describes the error:

```json theme={null}
{
  "success": false,
  "message": "Missing or invalid parameter to"
}
```

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Always `false` for an error. |
| `message` | string | Explanation of the error, such as the name of the parameter that failed validation. |

Use the HTTP status code to decide what to do. Don't parse `message`: its wording can change.

| Status | Meaning | What to do |
| - | - | - |
| `400`, `422` | A parameter is missing or invalid. | Don't retry. Fix the parameter named in `message`, then send the request again. |
| `401` | The API key is missing or invalid. | Don't retry. See [Authentication](https://docs.wavix.com/api-reference/authentication.md). |
| `403` | The API key isn't allowed to make this request. | Don't retry. Check the key's scopes and IP restriction. |
| `404` | The endpoint or object doesn't exist. | Don't retry. Check the URL path and the ID. |
| `429` | Your account sent too many requests. | Wait for the number of seconds in the `Retry-After` header, then retry. |
| `500`, `503` | A temporary error on the Wavix platform. | Retry with exponential backoff. |

### Problem details format

Some endpoints return errors in the problem details format. Today, these are the WhatsApp endpoints (`/v1/whatsapp/...`). The format follows [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) and uses the `application/problem+json` content type:

```json theme={null}
{
  "type": "https://docs.wavix.com/errors/sender-not-found",
  "title": "Sender Not Found",
  "status": 404,
  "detail": "No sender was found for that number on this account.",
  "instance": "3a525ca2-6909-4c72-9399-905adf7f3a74",
  "error_class": "permanent",
  "error_code": "SENDER_NOT_FOUND"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | URL of the page that explains the error and how to fix it. |
| `title` | string | Short summary of the error type. It's the same for every occurrence of the type. |
| `status` | integer | HTTP status code of the response. |
| `detail` | string | Explanation of this occurrence, such as the name of the field that failed validation. |
| `instance` | string | ID of the request. Include it when you contact Wavix support. |
| `error_class` | string | Whether retrying can help. See [Error classes](#error-classes). |
| `error_code` | string | Stable, machine-readable code of the error type, such as `SENDER_NOT_FOUND`. |

Use `error_code` in your code to tell errors apart. The `type` URL is the address of the error's page, and its last part, such as `sender-not-found`, names the same error. Don't parse `title` or `detail`: their wording can change.

Each error type has a page at the `type` URL that says what happened, whether to try again, and how to fix it.

#### Error classes

The `error_class` field tells you whether to retry the request:

| `error_class` | Meaning | What to do |
| - | - | - |
| `permanent` | The request can't succeed as sent. | Don't retry. Fix the request or the account setup, then send it again. |
| `retriable` | The failure is temporary. | Retry with exponential backoff. |
| `rate_limited` | Your account sent too many requests. | Wait for the number of seconds in the `Retry-After` header, then retry. |
| `invalid_template` | The message template content is invalid. | Don't retry. Fix the template, then submit it again. |

When you retry a WhatsApp message send, send the same `idempotency_key` with each attempt. The API then sends the message only once.

#### Handle problem details in your code

The following example sends a request and handles a problem details error. It retries `retriable` and `rate_limited` errors up to three times, and stops on any other error. It calls the WhatsApp senders endpoint, which returns this format:

```javascript Node.js theme={null}
// Node.js 18 or later
const API_KEY = "your_api_key";

async function wavixGet(path, attempt = 1) {
  const res = await fetch(`https://api.wavix.com${path}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (res.ok) return res.json();

  const problem = await res.json();
  const canRetry = ["retriable", "rate_limited"].includes(problem.error_class);
  if (canRetry && attempt <= 3) {
    const seconds = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    return wavixGet(path, attempt + 1);
  }
  throw new Error(`${problem.error_code}: ${problem.detail} (request ${problem.instance})`);
}

wavixGet("/v1/whatsapp/senders")
  .then((senders) => console.log(senders))
  .catch((err) => console.error(err.message));
```

```python Python theme={null}
# pip install requests
import time

import requests

API_KEY = "your_api_key"


def wavix_get(path):
    for attempt in range(1, 5):
        res = requests.get(
            f"https://api.wavix.com{path}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        if res.ok:
            return res.json()

        problem = res.json()
        can_retry = problem.get("error_class") in ("retriable", "rate_limited")
        if not can_retry or attempt == 4:
            raise RuntimeError(
                f"{problem['error_code']}: {problem['detail']} (request {problem['instance']})"
            )
        time.sleep(int(res.headers.get("Retry-After", 2 ** attempt)))


try:
    print(wavix_get("/v1/whatsapp/senders"))
except RuntimeError as err:
    print(err)
```

## Delivery errors

When a message you sent isn't delivered, Wavix tells you in a webhook. Where the error is and which codes it uses depends on the channel:

| Channel | Where the error is | Error list |
| - | - | - |
| SMS and MMS | The `error` field of the [delivery report](https://docs.wavix.com/messaging/webhooks-delivery-reports.md) | [SMS troubleshooting](https://docs.wavix.com/messaging/troubleshooting.md) |
| WhatsApp | The `data.error` field of the `whatsapp.message.failed` event, and the `error` field of [Retrieve a WhatsApp message](https://docs.wavix.com/api-reference/whatsapp/retrieve-a-whatsapp-message.md) and [List WhatsApp messages](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-messages.md) | [WhatsApp errors](https://docs.wavix.com/messaging/whatsapp/troubleshooting.md) |


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