Erros e respostas da API

Este artigo de referência aborda os vários erros e respostas do servidor que podem surgir ao usar a API da Braze e como solucioná-los.

Respostas do servidor

Se a carga útil do seu POST for aceita pelos nossos servidores, as mensagens bem-sucedidas recebem a seguinte resposta:

1
2
3

{
  "message" : "success"
}

Sucesso significa apenas que a carga útil da API RESTful foi formada corretamente e repassada aos nossos serviços de notificação por push, e-mail ou outros serviços de envio de mensagens. Isso não significa que as mensagens foram realmente entregues. Outros fatores podem impedir a entrega da mensagem: por exemplo, um dispositivo pode estar offline, o token por push pode ser rejeitado pelos servidores da Apple ou você pode ter informado um ID de usuário desconhecido.

Por que minha solicitação retorna sucesso quando nenhuma mensagem foi entregue?

Uma resposta message: success ou 2XX significa que a Braze aceitou e colocou na fila a solicitação para os endpoints envolvidos. Isso não significa que todos os destinatários receberam uma mensagem. No envio de mensagens, a entrega ainda depende da elegibilidade do canal, dos tokens, de erros do provedor e da validação do conteúdo. Consulte a tabela de erros fatais para ver os erros HTTP que bloqueiam envios e confira a análise de dados da sua Campaign ou do seu Canvas para ver as métricas de entrega posteriores.

Para endpoints como /users/identify, que não enviam mensagens, uma resposta de sucesso significa apenas que a Braze aceitou a solicitação para processamento. Se não existir nenhum usuário com o alias informado, ou se o alias pertencer a um perfil que já tem um external_id, a Braze ignora a identificação. A API ainda retorna a resposta inicial de sucesso, e nenhum erro indica que o alias não foi correspondido. Como alias_name diferencia maiúsculas de minúsculas, uma diferença de capitalização produz esse mesmo resultado.

Se a sua mensagem for bem-sucedida, mas tiver erros não fatais, você receberá a seguinte resposta:

1
2
3

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

Em caso de sucesso, todas as mensagens que não foram afetadas por um erro na matriz errors ainda serão entregues. Se a sua mensagem tiver um erro fatal, você receberá a seguinte resposta:

1
2
3

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

Respostas para IDs de envio rastreados

A análise de dados está sempre disponível para campanhas. Além disso, a análise de dados fica disponível para uma instância específica de envio de campanha quando a campanha é enviada como transmissão. Quando o rastreamento estiver disponível para uma instância específica de envio de campanha, você receberá a seguinte resposta:

1
2
3

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

O ID de envio fornecido pode ser usado como parâmetro no endpoint /send/data_series para obter a análise de dados específica do envio.

Erros

O elemento de código de status de uma resposta do servidor é um número de três dígitos. O primeiro dígito define a classe da resposta.

• A classe 2XX de código de status (não fatal) indica que sua solicitação foi recebida, compreendida e aceita com sucesso.
• A classe 4XX de código de status (fatal) indica um erro do cliente. Consulte a tabela de erros fatais para ver a lista completa de códigos de erro 4XX e suas descrições.
• A classe 5XX de código de status (fatal) indica um erro do servidor. Há várias causas possíveis. Por exemplo, o servidor que você está tentando acessar não consegue executar a solicitação, está em manutenção ou está com um volume alto de tráfego. Nesse caso, recomendamos que você tente enviar a solicitação novamente com backoff exponencial. Em caso de incidente ou interrupção, a Braze não consegue reprocessar nenhuma chamada da REST API que tenha falhado durante a janela do incidente. Você precisa repetir todas as chamadas que falharam nesse período.
  • Um erro 502 é uma falha que ocorre antes de a solicitação chegar ao servidor de destino.
  • Um erro 503 significa que a solicitação chegou ao servidor de destino, mas não conseguimos concluí-la por falta de capacidade, por um problema de rede ou por motivo semelhante.
  • Um erro 504 indica que um servidor não recebeu resposta de outro servidor upstream.

Erros fatais

Os códigos de status e as mensagens de erro a seguir são retornados quando sua solicitação encontra um erro fatal.

Aviso

Todos os códigos de erro a seguir indicam que nenhuma mensagem foi enviada.

Erro ao analisar o corpo da solicitação

A Braze retorna HTTP 400 quando o corpo da solicitação não é um JSON válido. Isso se aplica a endpoints REST que aceitam um corpo JSON, como POST, PUT e PATCH.

O campo error inclui uma mensagem informando que você precisa enviar application/json válido no corpo da solicitação. Você também pode ver Error while parsing request body. Please check your syntax.

As causas mais comuns são vírgulas finais, comentários dentro do JSON, strings entre aspas simples, um { de abertura extra antes da carga útil ou o envio de uma string concatenada em vez de um objeto codificado em JSON.

Antes de tentar novamente:

1. Valide a carga útil com um validador de JSON.
2. Defina Content-Type: application/json e envie JSON com codificação UTF-8.
3. Confirme que seu cliente HTTP codifica o objeto em JSON em vez de concatenar strings brutas.

Para saber mais sobre o tamanho da carga útil e os limites de objetos por solicitação de /users/track, consulte Por que recebo 400 Bad Request com um erro de sintaxe ou de análise?.