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

# Erreurs

> Une seule forme d’erreur, des codes stables.

Toutes les erreurs ont la même forme :

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Solde d’unités SMS insuffisant",
    "details": [{ "field": "units", "message": "120 unités requises, 40 disponibles" }],
    "requestId": "6a0f…",
    "timestamp": "2026-10-26T09:12:03.000Z"
  }
}
```

Décidez sur `code` et le statut HTTP, jamais sur `message`, qui peut changer. Gardez `requestId` : c’est ce que le support demande pour retrouver un appel.

| HTTP | `code` | Quand | Que faire |
| - | - | - | - |
| 400 | `VALIDATION_ERROR` | corps invalide ; `details` dit quel champ et pourquoi | corriger la requête, ne pas la rejouer telle quelle |
| 401 | `UNAUTHENTICATED` | clé absente, invalide, révoquée ou expirée | vérifier `x-api-key` |
| 402 | `INSUFFICIENT_BALANCE` | le solde du projet ne couvre pas l’envoi | acheter des unités, puis réessayer |
| 402 | `ACCOUNT_SUSPENDED` | production suspendue pour facture impayée | régler la facture depuis le dashboard |
| 403 | `ACCOUNT_SUSPENDED` | organisation suspendue par la plateforme ou son revendeur | contacter le support |
| 403 | `FORBIDDEN` | portée manquante | ajouter la portée à la clé |
| 404 | `NOT_FOUND` | ressource inexistante, ou d’un autre projet ou environnement | — |
| 409 | `CONFLICT` | `Idempotency-Key` déjà employée pour une autre demande ; doublon ; ressource plus modifiable | nouvelle clé, ou relire la ressource |
| 422 | `SENDER_NOT_APPROVED` | expéditeur SMS ni de la plateforme, ni approuvé | utiliser `DEXCHANGE` ou faire valider le nom |
| 422 | `KYC_REQUIRED` | dossier de l’organisation pas encore validé | compléter le dossier dans le dashboard |
| 422 | `DESTINATION_NOT_ALLOWED` | numéro valide, mais pays non ouvert | — |
| 422 | `NO_RECIPIENTS` | envoi sans aucun destinataire joignable | vérifier la cible |
| 422 | `TOO_MANY_RECIPIENTS` | plus de 200 000 destinataires | découper l’envoi |
| 422 | `CONTENT_BLOCKED` | une règle de contenu refuse le texte | revoir le texte |
| 429 | `RATE_LIMITED` | débit dépassé | attendre `Retry-After` secondes |
| 5xx | `INTERNAL_ERROR`, … | incident | réessayer avec la **même** `Idempotency-Key` |

> [!NOTE]
>
> `ACCOUNT_SUSPENDED` a deux statuts HTTP, et c’est le statut qui dit quoi faire : `402` se lève en payant, `403` non. Ne réessayez ni l’un ni l’autre en boucle.

## Numéros refusés

`400 VALIDATION_ERROR`, avec dans `details` le champ (`to`, ou `to.3` pour le quatrième numéro d’une liste) et un code stable : `PHONE_EMPTY`, `PHONE_INVALID_CHARACTERS`, `PHONE_INVALID_LENGTH`, `PHONE_INVALID_PREFIX`, `PHONE_UNKNOWN_COUNTRY`. Un texte trop long : `CONTENT_TOO_LONG`.

## Ce qui ne remonte pas en erreur HTTP

Les envois sont **asynchrones** : l’API répond `202` dès que le message est en file. Un refus de l’opérateur ou du fournisseur arrive plus tard, sur le destinataire (`status: failed` et son `errorCode`) et par [webhook](https://docs.dexnotify.com/webhooks.md).

## Réessayer

| Statut | Réessayer ? |
| - | - |
| erreur réseau, délai dépassé | oui, avec la même `Idempotency-Key` |
| `429` | oui, après `Retry-After` |
| `5xx` | oui, avec repli exponentiel et la même `Idempotency-Key` |
| `400`, `401`, `403`, `404`, `409`, `422` | non : la même requête aura la même réponse |
| `402` | après avoir rechargé le solde ou réglé la facture |


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