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 foi aceita pelos nossos servidores, mensagens bem-sucedidas recebem a seguinte resposta:

1
2
3

{
  "message" : "success"
}

Observe que “success” significa apenas que a carga útil da API RESTful foi formada corretamente e encaminhada para 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 de fato entregues, já que fatores adicionais 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 fornecido um ID de usuário desconhecido).

Por que minha solicitação retorna “success” quando nenhuma mensagem foi entregue?

Uma resposta message: success ou 2XX significa que a Braze aceitou e enfileirou a solicitação para os endpoints envolvidos — não que todos os destinatários receberam uma mensagem. Para envio de mensagens, a entrega ainda depende da elegibilidade do canal, tokens, erros do provedor e validação de conteúdo. Consulte a tabela de erros fatais para erros HTTP que bloqueiam envios, e as análises da sua Campaign ou Canvas para métricas de entrega downstream.

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 nenhum usuário existir com o alias fornecido, ou se o alias pertencer a um perfil que já possui um external_id, a Braze ignora a identificação. A API ainda retorna a resposta inicial de sucesso; não há erro indicando que o alias não foi correspondido. Como alias_name é sensível a maiúsculas e minúsculas, uma diferença de capitalização produz esse mesmo resultado.

Se 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>]
}

No caso de sucesso, todas as mensagens que não foram afetadas por um erro no array errors ainda serão entregues. Se 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 Campaigns. Além disso, a análise de dados está disponível para uma instância de envio específica de uma Campaign quando ela é enviada como broadcast. Quando o rastreamento está disponível para uma instância de envio específica de uma Campaign, você recebe a seguinte resposta:

1
2
3

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

O ID de envio fornecido pode ser usado como parâmetro para o endpoint /send/data_series para obter 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 3 dígitos em que o primeiro dígito do código 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, o servidor está em manutenção e não consegue executar a solicitação, ou o servidor está enfrentando altos níveis de tráfego. Quando isso acontecer, recomendamos que você tente novamente a solicitação com backoff exponencial. No caso de um incidente ou interrupção, a Braze não consegue reproduzir nenhuma chamada de REST API que falhou durante a janela do incidente. Você deve tentar novamente todas as chamadas que falharam durante a janela do incidente.
  • Um erro 502 é uma falha 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 foi possível completá-la porque não há capacidade suficiente, há um problema de rede ou algo semelhante.
  • Um erro 504 indica que um servidor não recebeu uma resposta de outro servidor upstream.

Erros fatais

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

Aviso

Todos os códigos de erro a seguir indicam que nenhuma mensagem é 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ê deve enviar application/json válido no corpo da solicitação. Você também pode ver Error while parsing request body. Please check your syntax.

Causas comuns incluem vírgulas finais, comentários dentro do JSON, strings com aspas simples, uma chave { 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 linter de JSON.
2. Defina Content-Type: application/json e envie JSON codificado em UTF-8.
3. Confirme que seu cliente HTTP codifica o objeto em JSON em vez de concatenar strings brutas.

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