Erreurs et réponses d’API

Cet article de référence couvre les diverses erreurs et réponses du serveur qui peuvent apparaître lors de l’utilisation de l’API Braze et la façon de les résoudre.

Réponses du serveur

Si nos serveurs acceptent le payload de votre requête POST, les messages traité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 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 bien é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 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 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 en vue de son 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 traité 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 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 :

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 également disponibles pour une instance d’envoi de Campaign spécifique lorsque la Campaign est envoyée en diffusion. Lorsque le suivi est disponible pour une instance d’envoi de Campaign 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

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

• Les codes de statut de la classe 2XX (non fatals) indiquent que votre requête a bien été reçue, comprise et acceptée.
• Les codes de statut de la classe 4XX (fatals) indiquent une erreur client. Consultez le tableau des erreurs fatales pour obtenir la liste complète des codes d’erreur 4XX et leur description.
• Les codes de statut de la classe 5XX (fatals) indiquent 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 maintenance et ne peut donc pas l’exécuter, ou il 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 rejouer aucun appel REST API ayant é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 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 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 contient un message indiquant que vous devez transmettre un application/json valide dans le corps de la requête. Vous pouvez également voir le message Error while parsing request body. Please check your syntax.

Parmi les causes fréquentes : des virgules finales, des commentaires dans le JSON, des chaînes 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 à l’aide d’un linter JSON.
2. Définissez Content-Type: application/json et envoyez du JSON encodé en UTF-8.
3. Vérifiez que votre client HTTP encode bien l’objet en JSON au lieu de concaténer des chaînes brutes.

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