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 :

1
2
3

{
  "message" : "success"
}

Notez qu’un succès signifie uniquement que le payload de l’API RESTful était correctement formé et a été transmis à nos services de notification push, d’e-mail ou d’autres services d’envoi de messages. Il ne signifie pas que les messages ont réellement été distribués, car d’autres facteurs peuvent empêcher leur distribution. Par exemple, un appareil peut être hors ligne, le jeton 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 mise en file d’attente pour les endpoints concernés. Elle ne signifie pas que chaque destinataire a reçu un message. Pour l’envoi de messages, la distribution dépend toujours de l’éligibilité au canal, des jetons, des erreurs du fournisseur 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 et 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 :

1
2
3

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

En cas de succès, tous les messages qui n’ont pas été affecté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 :

1
2
3

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

Réponses pour les ID d’envoi suivis

Les analyses sont toujours disponibles pour les Campaigns. Elles sont aussi disponibles pour une instance d’envoi spécifique d’une Campaign lorsque celle-ci est envoyée en diffusion. Lorsque le suivi est disponible pour une instance d’envoi spécifique, vous recevez la réponse suivante :

1
2
3

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

Vous pouvez utiliser l’ID d’envoi fourni comme paramètre de l’endpoint /send/data_series pour 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 à trois chiffres, dont le premier chiffre définit la classe de la réponse.

• La classe 2XX de code de statut (non fatale) indique que votre requête a bien été reçue, comprise et acceptée.
• La classe 4XX de code 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 code 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, il est en cours de maintenance et ne peut donc pas l’exécuter, ou il subit un trafic important. 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 à la REST API qui ont échoué pendant la période de l’incident. Vous devez relancer vous-même tous les appels qui ont échoué pendant cette période.
  • Une erreur 502 est un échec survenu avant que la requête n’atteigne le serveur de destination.
  • Une erreur 503 signifie que la requête a bien 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 suivants sont renvoyés si votre requête rencontre une erreur fatale.

Avertissement

Tous les codes d’erreur suivants indiquent qu’aucun message n’est envoyé.

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 inclut 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.

Parmi les causes courantes, on trouve 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 au lieu de concaténer des chaînes brutes.

Pour connaître 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 ?.