Codes d'erreur de l'API
Chaque code d'erreur de l'API Outbound avec son statut HTTP, sa signification et sa solution, pour que ton intégration réagisse correctement.
Si l'API Outbound refuse une requête, elle répond avec success: false, un code fixe dans error et une explication dans message. Ton intégration se base sur error, pas sur le texte : les codes restent stables, les textes peuvent changer.
{
"success": false,
"error": "invalid_to_number",
"message": "toNumber must be an international number in E.164 format …"
}
Vue d'ensemble
| Statut | Signification | Réessayer ? |
|---|---|---|
| 400 | La requête est incomplète ou invalide | seulement après correction |
| 401 | L'authentification manque ou est invalide | seulement après correction |
| 402 | Il manque un abonnement ou un paiement pour cette voie | seulement après paiement |
| 403 | Cette action n'est pas encore autorisée pour ton compte ou le numéro | seulement après autorisation |
| 409 | Une requête avec le même Idempotency-Key est encore en cours | oui, après Retry-After |
| 422 | La requête ne correspond pas à la configuration | seulement après correction |
| 429 | Limite atteinte | oui, après Retry-After |
| 500, 503 | Erreur de notre côté | oui, après un délai et avec le même Idempotency-Key |
400 : requête invalide
invalid_to_number
Le numéro de destination n'est pas au format E.164. Écris-le avec le signe plus et l'indicatif du pays, par exemple +491701234567. L'API refuse les formats nationaux comme 0170 …, car le pays ne peut pas en être déduit avec certitude.
invalid_from_number
Le numéro appelant n'est pas au format E.164. Écris-le comme le numéro de destination, avec le signe plus et l'indicatif du pays.
outbound_number_required
fromNumber manque. Indique ton numéro appelant : un numéro importé ou connecté via SIP, auquel un agent est attribué.
platform_number_inbound_only
Le numéro appelant est un numéro acheté chez bhomy. Ces numéros ne font que recevoir des appels. Importe ton propre numéro ou connecte-le via SIP.
invalid_idempotency_key
Le header Idempotency-Key est vide, dépasse 255 caractères ou contient des caractères hors ASCII. Utilise par exemple un UUID.
validation_error
Le numéro appelant n'a pas pu être vérifié pour le moment. Réessaie un peu plus tard.
Si le body manque ou n'est pas un JSON valide, l'API répond aussi avec 400, avec alors une explication dans error, par exemple « Missing required field: toNumber ».
401 : authentification
En cas de 401, la raison figure dans code :
code | Solution |
|---|---|
auth.missing_header | Envoie le header Authorization: Bearer … |
auth.invalid_type | Le header commence par Bearer suivi d'un espace |
auth.invalid_key | Cette clé n'existe pas. Vérifie qu'elle ne contient ni espaces ni retours à la ligne |
auth.key_revoked | La clé est désactivée. Réactive-la sous Clé API ou utilise-en une autre |
Plus d'informations dans Problèmes de clés API.
402 : paiement
imported_number_subscription
Les appels depuis un numéro importé nécessitent un abonnement actif sans facture impayée. Règle les factures ouvertes dans Facturation.
403 : pas encore autorisé
identity_not_verified
Via l'API, bhomy n'appelle qu'une fois ton identité confirmée. La réponse contient verify_url, le lien vers la carte Identité dans Facturation. Tu ne fais la vérification qu'une fois, voir Appels sortants.
sender_not_verified
Le numéro appelant n'est pas encore confirmé pour les appels sortants. Confirme-le avec l'appel de vérification dans ses paramètres sous Numéro de téléphone.
outbound_disabled
Les appels sortants ne sont pas configurés pour ce numéro SIP. Connecte-le avec l'adresse de terminaison et les identifiants de ton opérateur.
409 : encore en cours
idempotency_request_in_progress
Une requête avec le même Idempotency-Key est en cours de traitement. Attends le nombre de secondes indiqué dans Retry-After et renvoie la même requête. Tu reçois alors la réponse de la première.
422 : ne correspond pas à la configuration
idempotency_key_reused
Ce Idempotency-Key appartient déjà à une autre requête. Utilise une nouvelle clé pour chaque nouvel appel.
no_assistant_mapped
Aucun agent n'est attribué au numéro appelant. Attribue-lui un agent sous Numéro de téléphone.
imported_number_destination
Un numéro importé appelle les numéros fixes et mobiles allemands. Pour d'autres destinations, utilise un numéro SIP via ton propre opérateur.
429 : limite atteinte
rate_limit_exceeded
Plus de 60 requêtes en 60 secondes. limit_scope indique la limite : par adresse IP ou par clé API. Attends le nombre de secondes indiqué dans Retry-After et répartis tes requêtes.
concurrent_limit_reached
Toutes les lignes sont occupées. Avec limit_scope: "account", il s'agit des appels simultanés de ton forfait, et la réponse indique alors current et limit. Avec limit_scope: "platform", bhomy réserve brièvement des lignes pour les appels entrants. Dans les deux cas, attends le nombre de secondes indiqué dans Retry-After.
500 et 503 : erreur de notre côté
outbound_not_configured
Les appels sortants ne sont pas configurés de notre côté pour le moment. Contacte le support.
outbound_unavailable
Le service des appels sortants est temporairement indisponible. Réessaie dans quelques minutes.
dispatch_failed
L'agent n'a pas pu être envoyé. Réessaie avec le même Idempotency-Key, ainsi aucun appel en double n'est créé.
internal_error
Une erreur inattendue. Réessaie. Si l'erreur persiste, écris-nous.
Pour ces erreurs, la réponse contient souvent error_id. Envoie-le-nous, voir Signaler un problème. Nous retrouvons ainsi l'opération immédiatement.
Quand la demande a été acceptée mais qu'aucune conversation n'a eu lieu
Une réponse 202 signifie que la demande a été acceptée. Ce qui se passe ensuite apparaît comme résultat de l'appel dans l'historique des appels, par exemple Sans réponse, Messagerie ou Bloqué si ton compte était bloqué. Les résultats sont expliqués dans Campagnes.
Cette page vous a-t-elle aidé ?