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 votre payload POST a été accepté par nos serveurs, les messages réussis reçoivent la réponse suivante :

1
2
3

{
  "message" : "success"
}

Notez que « success » signifie uniquement que le payload de l’API RESTful a été correctement formé et transmis à nos services de notification push, d’e-mail ou de tout autre service de communication. Cela ne signifie pas que les messages ont effectivement été distribués, car d’autres facteurs pourraient empêcher la distribution du message (par exemple, un appareil pourrait être hors ligne, le jeton push pourrait être rejeté par les serveurs d’Apple, ou vous pourriez avoir 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é et mis en file d’attente la requête pour les endpoints concernés — et non que chaque destinataire a reçu un message. Pour les communications, la distribution dépend encore de l’éligibilité au canal, des jetons, des erreurs du fournisseur et de la validation du contenu. Consultez le tableau des erreurs fatales pour les erreurs HTTP qui bloquent les envois, ainsi que les analyses de votre Campaign ou 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 toujours 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 capitalisation produit le même résultat.

Si votre message a abouti mais comporte des erreurs non fatales, vous recevez la réponse suivante :

1
2
3

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

Dans le cas d’un succès, tous les messages qui n’ont pas été affectés par une erreur dans le 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 identifiants d’envoi suivis

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

1
2
3

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

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

Erreurs

L’élément de code de statut d’une réponse serveur est un nombre à 3 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 été reçue, comprise et acceptée avec succès.
• La classe 4XX de code de statut (fatale) indique une erreur client. Consultez le tableau des erreurs fatales pour une liste complète des codes d’erreur 4XX et leurs descriptions.
• La classe 5XX de code de statut (fatale) indique une erreur serveur. Il existe plusieurs causes potentielles, par exemple, le serveur auquel vous essayez d’accéder est incapable d’exécuter la requête, le serveur est en maintenance et ne peut pas exécuter la requête, ou le serveur subit un niveau de trafic élevé. Dans ce cas, nous vous recommandons de réessayer votre requête avec des délais exponentiels. En cas d’incident ou de panne, Braze n’est pas en mesure de rejouer les appels REST API qui ont échoué pendant la fenêtre de l’incident. Vous devez réessayer tous les appels qui ont échoué pendant la fenêtre de l’incident.
  • Une erreur 502 est un échec 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 car la capacité est insuffisante, ou en raison d’un problème réseau, ou d’une cause 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 suivants et les messages d’erreur associés 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 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 courantes incluent les virgules finales, les commentaires dans le JSON, les chaînes entre guillemets simples, une accolade ouvrante { supplémentaire avant le payload, ou l’envoi d’une chaîne concaténée au lieu d’un objet encodé en JSON.

Avant de réessayer :

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

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