Référence

Erreurs et statuts

Deux résultats comptent : la réponse HTTP à votre requête, puis le statut du message ensuite. Cette page couvre les deux.

Codes de statut HTTP

Statut	Signification	Réessayer ?
`200 OK`	La requête est acceptée. Pour un envoi : en file, pas encore remis.	Non
`400 Bad Request`	Le corps est invalide : champ manquant, mauvais type, numéro mal formé.	Non, corrigez la requête
`401 Unauthorized`	Clé API absente ou invalide.	Non
`403 Forbidden`	La clé n’a pas accès à cet endpoint ou à cette fonctionnalité.	Non
`404 Not Found`	Chemin inconnu, ou la ressource (appel, PIN, application) n’existe pas.	Non
`429 Too Many Requests`	Vous envoyez plus vite que votre compte ne le permet.	Oui, avec backoff
`5xx`	Un problème de notre côté.	Oui, avec backoff

Les endpoints SMS et RCS renvoient un errorCode sur lequel brancher votre logique, une description lisible, une action suggérée et, pour les requêtes invalides, la liste des violations avec le champ en cause.

SMS et RCS · 400 Bad Request

{  "errorCode": "E400",  "description": "Request cannot be processed.",  "action": "Check the syntax, violations and adjust the request.",  "violations": [    { "property": "messages[0].destinations[0].to", "violation": "must not be blank" }  ],  "resources": []}

La voix, la vérification et la boîte de réception SMS utilisent une forme plus ancienne : un objet requestError.serviceException avec un code messageId (BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, TOO_MANY_REQUESTS, GENERAL_ERROR) et un text. L’utilitaire client lit les deux : err.message est toujours renseigné.

Voix et vérification · 404 Not Found

{  "requestError": {    "serviceException": {      "messageId": "NOT_FOUND",      "text": "Not found"    }  }}

send.ts

import { pulsr, PulsrError } from "./client";try {  await pulsr("POST", "/sms/3/messages", { messages: [/* ... */] });} catch (err) {  if (err instanceof PulsrError) {    if (err.status === 429 || err.status >= 500) {      // Temporary: retry later with exponential backoff    } else {      // Permanent: fix the request, do not retry as is      console.error(err.status, err.message, err.body?.violations);    }  }  throw err;}

Statuts de message

Les réponses d’envoi, les rapports de remise et les logs décrivent chaque message avec un objet status, et les rapports y ajoutent un objet error. Basez votre logique sur groupName et gardez name pour les logs et le support.

Objets status et error

{  "status": {    "groupId": 3,    "groupName": "DELIVERED",    "id": 5,    "name": "DELIVERED_TO_HANDSET",    "description": "Message delivered to handset"  },  "error": {    "groupId": 0,    "groupName": "OK",    "id": 0,    "name": "NO_ERROR",    "description": "No Error",    "permanent": false  }}

groupName	groupId	Signification	Final ?
`PENDING`	`1`	Accepté et en route. `PENDING_ACCEPTED` juste après l’envoi, `PENDING_WAITING_DELIVERY` une fois transmis à l’opérateur.	Non
`DELIVERED`	`3`	Reçu par le téléphone (`DELIVERED_TO_HANDSET`), ou par l’opérateur quand le téléphone ne renvoie pas d’accusé.	Oui
`UNDELIVERABLE`	`2`	L’opérateur ou le téléphone l’a refusé. L’objet `error` dit pourquoi.	Oui
`EXPIRED`	`4`	La période de validité s’est écoulée avant la remise.	Oui
`REJECTED`	`5`	Pulsr ne l’a pas envoyé : destination invalide, expéditeur bloqué, crédit insuffisant ou pays bloqué.	Oui

Groupes d’erreurs

L’objet error d’un rapport a ses propres groupes. permanent: true signifie que renvoyer le même message au même numéro échouera de nouveau.

groupName	groupId	Cause typique
`OK`	`0`	Aucune erreur.
`HANDSET_ERRORS`	`1`	Téléphone éteint, hors couverture, mémoire pleine ou incapable d’afficher le message.
`USER_ERRORS`	`2`	Le numéro n’existe pas, est inactif ou a bloqué l’expéditeur.
`OPERATOR_ERRORS`	`3`	Le réseau mobile a refusé ou n’a pas pu acheminer le message.

Codes de statut HTTP

Statut	Signification	Réessayer ?
`200 OK`	La requête est acceptée. Pour un envoi : en file, pas encore remis.	Non
`400 Bad Request`	Le corps est invalide : champ manquant, mauvais type, numéro mal formé.	Non, corrigez la requête
`401 Unauthorized`	Clé API absente ou invalide.	Non
`403 Forbidden`	La clé n’a pas accès à cet endpoint ou à cette fonctionnalité.	Non
`404 Not Found`	Chemin inconnu, ou la ressource (appel, PIN, application) n’existe pas.	Non
`429 Too Many Requests`	Vous envoyez plus vite que votre compte ne le permet.	Oui, avec backoff
`5xx`	Un problème de notre côté.	Oui, avec backoff

Corps d’erreur

SMS et RCS · 400 Bad Request

{  "errorCode": "E400",  "description": "Request cannot be processed.",  "action": "Check the syntax, violations and adjust the request.",  "violations": [    { "property": "messages[0].destinations[0].to", "violation": "must not be blank" }  ],  "resources": []}

Voix et vérification · 404 Not Found

{  "requestError": {    "serviceException": {      "messageId": "NOT_FOUND",      "text": "Not found"    }  }}

send.ts

import { pulsr, PulsrError } from "./client";try {  await pulsr("POST", "/sms/3/messages", { messages: [/* ... */] });} catch (err) {  if (err instanceof PulsrError) {    if (err.status === 429 || err.status >= 500) {      // Temporary: retry later with exponential backoff    } else {      // Permanent: fix the request, do not retry as is      console.error(err.status, err.message, err.body?.violations);    }  }  throw err;}

Statuts de message

Objets status et error

{  "status": {    "groupId": 3,    "groupName": "DELIVERED",    "id": 5,    "name": "DELIVERED_TO_HANDSET",    "description": "Message delivered to handset"  },  "error": {    "groupId": 0,    "groupName": "OK",    "id": 0,    "name": "NO_ERROR",    "description": "No Error",    "permanent": false  }}

groupName	groupId	Signification	Final ?
`PENDING`	`1`	Accepté et en route. `PENDING_ACCEPTED` juste après l’envoi, `PENDING_WAITING_DELIVERY` une fois transmis à l’opérateur.	Non
`DELIVERED`	`3`	Reçu par le téléphone (`DELIVERED_TO_HANDSET`), ou par l’opérateur quand le téléphone ne renvoie pas d’accusé.	Oui
`UNDELIVERABLE`	`2`	L’opérateur ou le téléphone l’a refusé. L’objet `error` dit pourquoi.	Oui
`EXPIRED`	`4`	La période de validité s’est écoulée avant la remise.	Oui
`REJECTED`	`5`	Pulsr ne l’a pas envoyé : destination invalide, expéditeur bloqué, crédit insuffisant ou pays bloqué.	Oui

Groupes d’erreurs

L’objet error d’un rapport a ses propres groupes. permanent: true signifie que renvoyer le même message au même numéro échouera de nouveau.

groupName	groupId	Cause typique
`OK`	`0`	Aucune erreur.
`HANDSET_ERRORS`	`1`	Téléphone éteint, hors couverture, mémoire pleine ou incapable d’afficher le message.
`USER_ERRORS`	`2`	Le numéro n’existe pas, est inactif ou a bloqué l’expéditeur.
`OPERATOR_ERRORS`	`3`	Le réseau mobile a refusé ou n’a pas pu acheminer le message.