Passer au contenu

Erreurs et réponses de l’API

Cet article de référence présente les différentes erreurs et réponses du serveur que vous pouvez rencontrer lors de l’utilisation de l’API Braze, ainsi que la manière de les résoudre.

Réponses du serveur

Si nos serveurs acceptent votre payload POST, les messages envoyés avec succès reçoivent la réponse suivante :

{
  "message" : "success"
}

Notez qu’un succès signifie uniquement que le payload de l’API RESTful était correctement formé et qu’il a été transmis à nos services de notification push, d’e-mail ou d’autres services d’envoi de messages. Cela ne signifie pas que les messages ont réellement été distribués : d’autres facteurs peuvent empêcher la distribution du message (par exemple, un appareil peut être hors ligne, le jeton de notification push peut être rejeté par les serveurs d’Apple, ou vous avez peut-être fourni un ID utilisateur inconnu).

Pourquoi ma requête renvoie-t-elle un succès alors qu’aucun message n’a été distribué ?

Une réponse message: success ou 2XX signifie que Braze a accepté la requête et l’a placée en file d’attente pour les endpoints concernés, et non que chaque destinataire a reçu un message. Pour l’envoi de messages, la distribution dépend encore de l’éligibilité au canal, des jetons, des erreurs des fournisseurs et de la validation du contenu. Consultez le tableau des erreurs fatales pour connaître les erreurs HTTP qui bloquent les envois, ainsi que les analyses de votre Campaign ou de votre Canvas pour les indicateurs de distribution en aval.

Pour les endpoints comme /users/identify, qui n’envoient pas de messages, une réponse de succès signifie uniquement que Braze a accepté la requête pour traitement. Si aucun utilisateur n’existe avec l’alias fourni, ou si l’alias appartient à un profil qui possède déjà un external_id, Braze ignore l’identification. L’API renvoie tout de même la réponse de succès initiale ; aucune erreur n’indique que l’alias n’a pas été trouvé. Comme alias_name est sensible à la casse, une différence de majuscules ou de minuscules produit le même résultat.

Si votre message est envoyé avec succès mais comporte des erreurs non fatales, vous recevez la réponse suivante :

{
  "message" : "success", "errors" : [<minor error message>]
}

En cas de succès, tous les messages qui ne sont pas concernés par une erreur du tableau errors sont tout de même distribués. Si votre message comporte une erreur fatale, vous recevez la réponse suivante :

{
  "message" : <fatal error message>, "errors" : [<minor error message>]
}

Réponses pour les ID d’envoi suivis

Les analyses sont toujours disponibles pour les campagnes. De plus, des analyses sont disponibles pour une instance d’envoi de campagne spécifique lorsque la campagne est envoyée en tant que diffusion. Lorsque le suivi est disponible pour une instance d’envoi de campagne spécifique, vous recevez la réponse suivante :

{
  "message": "success", "send_id" : "example_send_id"
}

L’ID d’envoi fourni peut être utilisé comme paramètre pour l’endpoint /send/data_series afin de récupérer les analyses propres à cet envoi.

Erreurs

L’élément de code de statut d’une réponse du serveur est un nombre à 3 chiffres dont le premier chiffre définit la classe de la réponse.

  • La classe 2XX de codes de statut (non fatale) indique que votre requête a bien été reçue, comprise et acceptée.
  • La classe 4XX de codes de statut (fatale) indique une erreur client. Consultez le tableau des erreurs fatales pour obtenir la liste complète des codes d’erreur 4XX et leurs descriptions.
  • La classe 5XX de codes de statut (fatale) indique une erreur serveur. Plusieurs causes sont possibles : par exemple, le serveur auquel vous essayez d’accéder ne parvient pas à exécuter la requête, le serveur est en maintenance et ne peut donc pas exécuter la requête, ou le serveur subit un trafic élevé. Dans ce cas, nous vous recommandons de relancer votre requête avec des délais exponentiels. En cas d’incident ou de panne, Braze ne peut pas rejouer les appels REST API qui ont échoué pendant la période de l’incident. Vous devez relancer vous-même tous les appels ayant échoué pendant cette période.
    • Une erreur 502 correspond à un échec survenu avant que la requête n’atteigne le serveur de destination.
    • Une erreur 503 signifie que la requête a atteint le serveur de destination, mais que nous ne pouvons pas la traiter en raison d’une capacité insuffisante, d’un problème réseau ou d’un problème similaire.
    • Une erreur 504 indique qu’un serveur n’a pas reçu de réponse d’un autre serveur en amont.

Erreurs fatales

Les codes de statut et messages d’erreur associés suivants sont renvoyés si votre requête rencontre une erreur fatale.

Code d’erreur Description
5XX Internal Server Error Relancez votre requête avec des délais exponentiels.
400 Bad Request Syntaxe incorrecte. Un JSON invalide renvoie une erreur HTTP 400. Le champ error peut contenir un message indiquant que vous devez transmettre un application/json valide dans le corps de la requête, ou Error while parsing request body. Please check your syntax. Consultez Erreur lors de l’analyse du corps de la requête.
400 No Recipients La requête ne contient aucun ID externe, aucun ID de segment ni aucun jeton de notification push.
400 Invalid Campaign ID Aucune campagne d’API de messagerie n’a été trouvée pour l’ID de campagne fourni.
400 Bad Request (transactional campaign) Les campagnes transactionnelles ne peuvent pas être déclenchées via cet endpoint. Utilisez plutôt l’endpoint /transactional/v1/campaigns/{campaign_id}/send. Renvoyé par /campaigns/trigger/send et /campaigns/trigger/schedule/create lorsque campaign_id correspond à une campagne d’e-mail transactionnel.
400 Message Variant Unspecified Vous avez fourni un ID de campagne, mais aucun ID de variante de message.
400 Invalid Message Variant Vous avez fourni un ID de campagne valide, mais l’ID de variante de message ne correspond à aucun des messages de cette campagne.
400 Mismatched Message Type Vous avez fourni une variante de message d’un type de message incorrect pour au moins un de vos messages.
400 Invalid Extra Push Payload Vous avez fourni la clé extra pour apple_push ou android_push, mais il ne s’agit pas d’un dictionnaire.
400 Max Input Length Exceeded Pour /users/track, cette erreur est due au dépassement du nombre maximal d’objets autorisés dans une seule requête. La limite dépend du modèle de limitation du débit : pour la plupart des clients, chaque requête accepte jusqu’à 75 objets au total, tous attributes, events et purchases confondus. Pour les clients soumis aux anciennes limites de débit, chaque tableau accepte jusqu’à 75 objets de manière indépendante. Pour en savoir plus, consultez POST : Créer et mettre à jour des utilisateurs.
400 The max number of external_ids and aliases per request was exceeded Causée par l’appel de plus de 50 ID externes.
400 The max number of ids per request was exceeded Causée par l’appel de plus de 50 ID externes.
400 No message to send Aucun payload n’est spécifié pour le message.
400 Slideup Message Length Exceeded Le message contextuel contient plus de 140 caractères.
400 Apple Push Length Exceeded Le payload JSON dépasse 1 912 octets.
400 Android Push Length Exceeded Le payload JSON dépasse 4 000 octets.
400 Bad Request Impossible d’analyser la date et l’heure send_at.
400 Bad Request Dans votre requête, in_local_time est défini sur true, mais l’heure time est déjà passée dans le fuseau horaire de votre entreprise.
401 Unauthorized Clé API invalide. Causes fréquentes :

- En-tête Authorization manquant ou mal formé. La valeur de l’en-tête doit être Bearer suivi d’un espace, puis de votre clé API : Authorization: Bearer YOUR-API-KEY. Les erreurs courantes consistent à omettre Bearer, à omettre la clé après Bearer ou à placer la valeur entre guillemets.
- Mauvais endpoint REST. Vous envoyez la requête à la mauvaise instance. Par exemple, si votre compte se trouve sur notre instance européenne (https://dashboard-01.braze.eu), la requête doit être envoyée à https://rest.fra-01.braze.eu.
- Autorisations insuffisantes. Chaque clé API est limitée à un espace de travail et à un ensemble d’autorisations spécifiques. Vérifiez les autorisations de la clé dans Paramètres > Clés API dans le tableau de bord.
- Mauvaise clé API. Les clés API sont propres à chaque espace de travail. Une clé provenant d’un espace de travail ne peut pas être utilisée pour authentifier des requêtes destinées à un autre espace de travail.
403 Forbidden Le forfait ne le permet pas, ou le compte est désactivé pour une autre raison.
403 Access Denied La clé REST API que vous utilisez ne dispose pas des autorisations suffisantes. Causes fréquentes :
  • La clé API est antérieure à la fonctionnalité. Si la clé API a été créée avant le lancement d’une fonctionnalité (comme les groupes d’abonnement ou les catalogues), elle n’hérite pas automatiquement de ces autorisations. Créez une nouvelle clé API avec les autorisations requises dans Paramètres > Clés API.
  • Autorisation spécifique à l’endpoint manquante. Chaque endpoint de l’API requiert une autorisation spécifique (par exemple, users.track ou email.status). Vérifiez que les autorisations de la clé correspondent à l’endpoint que vous appelez.
  • Barre oblique finale ou faute de frappe dans l’URL. Par exemple, /users/track/ (avec une barre oblique finale) au lieu de /users/track peut provoquer des erreurs inattendues.
404 Not Found URL invalide.
415 Unsupported Media Type L’en-tête de requête Content-Type est manquant ou incorrect. Dans la page Paramètres, ajoutez Content-Type avec la valeur application/json.
429 Rate Limited Limite de débit dépassée.

Erreur lors de l’analyse du corps de la requête

Braze renvoie une erreur HTTP 400 lorsque le corps de la requête n’est pas un JSON valide. Cela s’applique aux endpoints REST qui acceptent un corps JSON, comme POST, PUT et PATCH.

Le champ error contient un message indiquant que vous devez transmettre un application/json valide dans le corps de la requête. Vous pouvez également voir Error while parsing request body. Please check your syntax.

Les causes fréquentes incluent les virgules finales, les commentaires dans le JSON, les chaînes de caractères entre guillemets simples, une accolade ouvrante { en trop avant le payload, ou l’envoi d’une chaîne concaténée au lieu d’un objet encodé en JSON.

Avant de relancer votre requête :

  1. Validez le payload avec un linter JSON.
  2. Définissez Content-Type: application/json et envoyez un JSON encodé en UTF-8.
  3. Vérifiez que votre client HTTP encode l’objet en JSON plutôt que de concaténer des chaînes brutes.

Pour la taille du payload de /users/track et les limites d’objets par requête, consultez Pourquoi est-ce que je reçois une erreur 400 Bad Request avec une syntaxe incorrecte ou une erreur d’analyse ?.

New Stuff!