Erreurs

Chaque réponse 4xx et 5xx de l’API Lisoloo utilise la même forme JSON. Basez vos branchements sur error_code, jamais sur message — les messages sont localisés et peuvent changer pour plus de clarté ; les codes font partie du contrat public.

L’enveloppe

{
  "success": false,
  "status_code": 400,
  "error_code": "1101",
  "message": "Invalid amount or recipient list",
  "details": [
    {
      "field": "to[0]",
      "message": "Must match E.164 format",
      "code": "INVALID_PHONE_NUMBER"
    }
  ],
  "timestamp": "2026-05-27T10:15:00Z",
  "request_id": "req_8f3a4c2e9b1d7a6f",
  "retryable": false,
  "retry_after": null
}

Champ	Type	Notes
success	bool	Toujours false en erreur. Garde facile : if (!body.success) { … }.
status_code	int	Reflète le statut HTTP.
error_code	string	Code à quatre chiffres stable. Branchez là-dessus.
message	string	Lisible. Localisé par Accept-Language. Pour les opérations, pas les utilisateurs finaux.
details	array | null	Décomposition au niveau du champ pour les erreurs de validation (1110).
timestamp	ISO 8601	Heure serveur de génération.
request_id	string	À citer en contactant le support.
retryable	bool	true pour les échecs transitoires. Ne jamais auto-retry si false.
retry_after	int | null	Secondes à attendre si retryable: true (et 429).

Groupes de codes en un coup d’œil

Le premier chiffre groupe la cause :

Plage	Groupe	Exemples
1001–1005	Authentification	1001 INVALID_APP_KEY, 1004 APP_SUSPENDED
1101–1110	Validation de la requête	1101 INVALID_RECIPIENTS, 1104 INVALID_PHONE_NUMBER, 1109 MISSING_REQUIRED_FIELD
1201–1205	Logique métier	1202 INSUFFICIENT_BALANCE, 1203 RECIPIENT_LIMIT_EXCEEDED
1301–1305	Sécurité et limites	1301 RATE_LIMIT_EXCEEDED
1401–1405	Serveur / système	1401 INTERNAL_SERVER_ERROR, 1402 SERVICE_UNAVAILABLE
1501–1505	Opérateur / SMS	1502 SMS_REJECTED_BY_CARRIER, 1503 SMS_TIMEOUT

Le catalogue complet avec remédiation est au catalogue d’erreurs.

Branchement sur error_code

function handleLisolooError(body: {
  error_code: string;
  message: string;
  retryable: boolean;
  retry_after: number | null;
}) {
  switch (body.error_code) {
    case "1001": // INVALID_APP_KEY
    case "1004": // APP_SUSPENDED
      // Stop. Pas de retry. Remonter aux opérations.
      throw new AuthenticationFailed(body.message);

    case "1101": // INVALID_RECIPIENTS
    case "1104": // INVALID_PHONE_NUMBER
    case "1109": // MISSING_REQUIRED_FIELD
      // Mauvaise entrée chez nous. Corriger et ne pas retry le même body.
      throw new ValidationError(body.message);

    case "1202": // INSUFFICIENT_BALANCE
      // Remonter au tableau de bord, alerter ops, pas de retry.
      throw new BalanceExhausted(body.message);

    case "1301": // RATE_LIMIT_EXCEEDED
      // Respecter retry_after.
      return scheduleRetry(body.retry_after ?? 60);

    case "1402": // SERVICE_UNAVAILABLE
    case "1503": // SMS_TIMEOUT
      if (body.retryable) {
        return scheduleRetry(body.retry_after ?? 30);
      }
      throw new ProcessorFailure(body.message);

    default:
      throw new UnknownError(body.error_code, body.message);
  }
}

Correspondance des statuts HTTP

Certains codes correspondent à plusieurs statuts HTTP selon le contexte (par exemple 1004 APP_SUSPENDED est 403, tandis que 1001 INVALID_APP_KEY est 401). Le statut HTTP est la catégorie large ; error_code est la cause spécifique. Utilisez le statut HTTP pour le routage à travers le middleware (échecs d’auth vers un handler, échecs de validation vers un autre) ; utilisez error_code pour la logique réelle.

HTTP	Signification
400	Échec de validation. Pas de retry.
401	En-tête d’auth manquant ou invalide. Pas de retry.
402	Paiement requis (solde). Pas de retry.
403	Authentifié mais interdit (clé suspendue). Pas de retry.
404	Ressource introuvable (par exemple message_id inconnu).
429	Limité. Respecter Retry-After.
500	Erreur serveur. Retry sûr une fois avec backoff exponentiel.
502 / 503	Problème upstream / opérateur. Retry sûr.

details sur les échecs de validation

Quand la passerelle renvoie 1110 INVALID_FIELD_FORMAT (ou 1109 MISSING_REQUIRED_FIELD), le tableau details porte une entrée par champ échoué :

{
  "error_code": "1110",
  "message": "Field validation failed",
  "details": [
    { "field": "to[2]",       "message": "Must match E.164 format",        "code": "INVALID_PHONE_NUMBER" },
    { "field": "message",     "message": "Must be 1-1600 characters",      "code": "INVALID_LENGTH"       },
    { "field": "scheduled_dates[0].time", "message": "Must be HH:mm",      "code": "INVALID_TIME_FORMAT"  }
  ]
}

Le chemin field utilise une notation pointée style JSONPointer avec [n] pour les indices de tableau. Itérez details pour afficher les erreurs par champ dans votre UI.

Voir aussi

• Catalogue d’erreurs — chaque code avec remédiation
• Authentification — les modes d’échec d’auth
• Limites de débit — le contrat Retry-After