Catalogue d'erreurs

Chaque réponse d’erreur de l’API utilise l’enveloppe PaymentGatewayError avec un error_code stable à quatre chiffres. Cette page est le catalogue complet. Basez vos branchements sur error_code, jamais sur message.

Le premier chiffre groupe la cause :

• 10xx — Authentification
• 11xx — Validation
• 12xx — Logique métier
• 13xx — Sécurité
• 14xx — Système
• 15xx — Opérateur / SMS

10xx Authentification

Identifiants. Ne jamais auto-retry — celles-ci demandent une intervention humaine ou un nouvel identifiant.

Code	Symbole	Cause	Correctif
1001	INVALID_APP_KEY	La valeur app-key est inconnue, mal formée ou révoquée.	Vérifiez que la valeur de l’en-tête correspond à ce qui est dans le portail. Régénérez en cas de perte.
1002	APP_KEY_MISSING	Aucun en-tête app-key n’a été envoyé.	Ajoutez app-key: <votre_clé> à la requête.
1003	APP_NOT_ALLOWED	La clé est valide mais l’appelant n’est pas sur la liste blanche (mismatch CIDR IP).	Ajoutez l’IP source à la liste blanche de la clé API.
1004	APP_SUSPENDED	La clé est en état SUSPENDED.	Contactez votre gestionnaire de compte Bloonio. Pas de retry.
1005	APP_EXPIRED	Expiration matérielle dépassée.	Régénérez.

11xx Validation

Forme ou contenu de requête incorrect. Corrigez chez vous et ne retentez pas le même payload.

Code	Symbole	Cause	Correctif
1101	INVALID_RECIPIENTS	to est vide, trop long ou contient des valeurs non-string.	to est requis, max 1 000 entrées, chaque entrée doit être une string.
1102	INVALID_MESSAGE	message est vide ou > 1 600 caractères.	Tronquez ou divisez.
1103	INVALID_SENDER_ID	sender_id a des caractères illégaux ou dépasse 11 chars.	A–Z, 0–9, ≤11 chars.
1104	INVALID_PHONE_NUMBER	Une entrée de to ne correspond pas à ^\+?\d{1,15}$.	Formater en E.164 (+CCNNNNN…). Le tableau details montre quelles entrées ont échoué.
1105	INVALID_SENDING_TYPE	sending_type pas dans {immediate, scheduled, recurring}.	Utilisez l’une des trois valeurs.
1106	INVALID_SCHEDULED_DATE	Une entrée de scheduled_dates est mal formée ou dans le passé.	Utilisez YYYY-MM-DD pour date, HH:mm pour time, les deux en fuseau marchand, les deux ≥ maintenant.
1107	INVALID_RECURRING_SCHEDULE	L’objet recurring_schedule a des champs manquants ou des valeurs hors plage.	Voir Types d’envoi pour le schéma.
1108	INVALID_CALLBACK_URL	callback_url n’est pas une URL HTTPS valide.	Doit être https://….
1109	MISSING_REQUIRED_FIELD	Un champ requis manque pour le sending_type choisi.	Voir details pour le nom du champ.
1110	INVALID_FIELD_FORMAT	Échec de validation générique. Le tableau details a la décomposition.	Lisez details, corrigez chaque entrée.

12xx Logique métier

La requête était bien formée mais l’état métier l’interdit.

Code	Symbole	Cause	Correctif
1201	RECIPIENT_LIMIT_EXCEEDED	Plus de 1 000 destinataires en un appel.	Divisez en lots. Voir Envoyer un SMS instantané.
1202	INSUFFICIENT_BALANCE	Votre solde est sous le total_cost projeté.	Rechargez via le tableau de bord Bloonio. Retentez avec un lot plus petit ou après rechargement.
1203	RECURRING_LIMIT_EXCEEDED	Le planning récurrent générerait plus de 5 000 SMS.	Raccourcissez end_date, réduisez times, ou moins de destinataires.
1204	MESSAGE_NOT_FOUND	message_id n’existe pas, appartient à un autre marchand, ou a été purgé après 90 jours.	Vérifiez que l’ID est le vôtre.
1205	OPERATION_NOT_ALLOWED	Tentative de cancel/pause/resume d’un message non planifié ou récurrent (ou déjà dans un état terminal).	Vérifiez le status courant via GET /status.

13xx Sécurité

Limites de débit, IPs bloquées, anti-abus.

Code	Symbole	Cause	Correctif
1301	RATE_LIMIT_EXCEEDED	Limite de bucket atteinte.	Respectez Retry-After. Voir Limites de débit.
1302	SUSPICIOUS_ACTIVITY	Les heuristiques anti-abus ont signalé la requête.	Contactez le support si légitime.
1303	IP_BLOCKED	IP source sur une liste noire.	Utilisez un autre réseau ou faites appel aux ops.
1304	INVALID_WEBHOOK_AUTH	Le récepteur webhook a renvoyé 401 à plusieurs reprises.	Vérifiez que la config Basic auth correspond à la configuration de la clé API.
1305	REQUEST_TOO_LARGE	Corps de requête au-delà de la limite de 1 Mo.	Réduisez la taille — moins de destinataires par appel.

14xx Système

Problèmes côté serveur. La plupart sont transitoires et retryable: true.

Code	Symbole	Cause	Correctif
1401	INTERNAL_SERVER_ERROR	Exception non gérée dans la passerelle.	Retry avec backoff. Si persistant, contactez le support avec request_id.
1402	SERVICE_UNAVAILABLE	Passerelle en maintenance ou surchargée.	Retry après retry_after.
1403	DATABASE_ERROR	Échec de la couche de stockage.	Retry.
1404	EXTERNAL_API_ERROR	Dépendance upstream (connecteur opérateur, service de solde) a erré.	Retry.
1405	TIMEOUT_ERROR	Timeout interne.	Retry.

15xx Opérateur / SMS

Échecs du connecteur opérateur ou du SMSC sous-jacent.

Code	Symbole	Cause	Correctif
1501	CARRIER_UNAVAILABLE	Aucun connecteur opérateur disponible pour le pays de destination.	Contactez le support.
1502	SMS_REJECTED_BY_CARRIER	Le SMSC a rejeté le message (typiquement : numéro invalide, sender ID non enregistré pour la destination).	Vérifiez details pour la raison opérateur.
1503	SMS_TIMEOUT	Pas d’accusé de livraison sous 24 h.	Traité comme failed ; pas d’autre retry.
1504	SMS_BLOCKED	Le combiné de destination a bloqué l’expéditeur ou le message a été flaggé comme spam.	Contactez via un autre canal ; revoyez votre sender ID et le contenu du message.
1505	INSUFFICIENT_CARRIER_QUOTA	Le connecteur opérateur lui-même a un quota insuffisant avec le SMSC (niveau opérateur).	Problème côté Bloonio ; contactez le support. Sera retryable: true pour les cas transitoires.

Voir aussi

• Erreurs — l’enveloppe et le pattern de branchement
• Authentification — codes liés à l’auth
• Limites de débit — gestion de 1301
• Support — que envoyer en contactant le support