Erreurs - DexNotify

Toutes les erreurs ont la même forme :

{
  "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`

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.

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