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 POST for aceita pelos nossos servidores, as mensagens bem-sucedidas recebem a seguinte resposta:
{
"message" : "success"
}
Note que sucesso significa apenas que a carga útil da API RESTful foi formada corretamente e repassada aos nossos serviços de notificação por push, de e-mail ou de outro tipo de envio de mensagens. Isso não significa que as mensagens foram de fato entregues, já que outros fatores podem impedir a entrega. 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 a solicitação e a colocou na fila 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 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á tenha um external_id, a Braze ignora a identificação. A API ainda retorna a resposta inicial de sucesso, e não há nenhum erro indicando que o alias não foi encontrado. Como o alias_name diferencia maiúsculas de minúsculas, uma divergência 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:
{
"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 são entregues. Se a sua mensagem tiver um erro fatal, você receberá a seguinte resposta:
{
"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, ela também fica disponível para uma instância específica de envio da campanha quando a campanha é enviada como transmissão. Quando o rastreamento estiver disponível para uma instância específica de envio da campanha, você receberá a seguinte resposta:
{
"message": "success", "send_id" : "example_send_id"
}
Você pode usar o ID de envio fornecido 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 3 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, o servidor está em manutenção e por isso não consegue executá-la, ou o servidor está com um volume alto de tráfego. Nesse caso, recomendamos repetir a solicitação com backoff exponencial. Em caso de incidente ou interrupção, a Braze não consegue reproduzir nenhuma chamada da REST API que tenha falhado durante a janela do incidente. Você precisa repetir todas as chamadas que falharam durante esse 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 algo semelhante.
- Um erro 504 indica que um servidor não recebeu resposta de outro servidor upstream.
Erros fatais

Para erros 401 e 403, confirme o token Bearer no seu cabeçalho Authorization, o endpoint REST da instância do seu espaço de trabalho e as permissões da sua chave de API. Para erros de análise 400, valide a codificação JSON do corpo da sua solicitação. Para saber mais, consulte Erro ao analisar o corpo da solicitação. Para os limites de objetos do /users/track, consulte o limite de frequência do /users/track. Para os limites de tamanho da solicitação, consulte Limites de tamanho da carga útil. Os limites de frequência (429) são abordados separadamente em Limites de frequência.
Os códigos de status e as mensagens de erro associadas a seguir são retornados se sua solicitação encontrar um erro fatal.

Todos os códigos de erro a seguir indicam que nenhuma mensagem foi enviada.
| Código de erro | Descrição |
|---|---|
5XX Internal Server Error |
Repita a solicitação com backoff exponencial. |
400 Bad Request |
Sintaxe incorreta. Um JSON inválido retorna HTTP 400. O campo error pode incluir uma mensagem informando que você deve passar application/json válido no corpo da solicitação, ou Error while parsing request body. Please check your syntax. Consulte Erro ao analisar o corpo da solicitação. |
400 No Recipients |
Não há IDs externos, IDs de segmento ou tokens por push na solicitação. |
400 Invalid Campaign ID |
Nenhuma campanha da API de envio de mensagens foi encontrada para o ID de campanha informado. |
400 Bad Request (transactional campaign) |
Campanhas transacionais não podem ser disparadas por este endpoint. Use o endpoint /transactional/v1/campaigns/{campaign_id}/send em vez disso. Retornado por /campaigns/trigger/send e /campaigns/trigger/schedule/create quando o campaign_id pertence a uma campanha de e-mail de transação. |
400 Message Variant Unspecified |
Você informou um ID de campanha, mas nenhum ID de variação de mensagem. |
400 Invalid Message Variant |
Você informou um ID de campanha válido, mas o ID de variação de mensagem não corresponde a nenhuma das mensagens dessa campanha. |
400 Mismatched Message Type |
Você informou uma variação de mensagem com o tipo de mensagem errado para pelo menos uma das suas mensagens. |
400 Invalid Extra Push Payload |
Você informou a chave extra para apple_push ou android_push, mas ela não é um dicionário. |
400 Max Input Length Exceeded |
No /users/track, esse erro ocorre quando você excede o número máximo de objetos permitidos em uma única solicitação. O limite depende do modelo de limite de frequência: para a maioria dos clientes, cada solicitação aceita até 75 objetos no total, somando attributes, events e purchases. Para clientes com limites de frequência legados, cada array aceita até 75 objetos de forma independente. Para saber mais, consulte POST: Criar e atualizar usuários. |
400 The max number of external_ids and aliases per request was exceeded |
Ocorre ao chamar mais de 50 IDs externos. |
400 The max number of ids per request was exceeded |
Ocorre ao chamar mais de 50 IDs externos. |
400 No message to send |
Nenhuma carga útil foi especificada para a mensagem. |
400 Slideup Message Length Exceeded |
A mensagem slideup tem mais de 140 caracteres. |
400 Apple Push Length Exceeded |
A carga útil JSON tem mais de 1.912 bytes. |
400 Android Push Length Exceeded |
A carga útil JSON tem mais de 4.000 bytes. |
400 Bad Request |
Não é possível analisar a data e hora de send_at. |
400 Bad Request |
Na sua solicitação, in_local_time é verdadeiro, mas o time já passou no fuso horário da sua empresa. |
401 Unauthorized |
Chave de API inválida. As causas mais comuns são: - Cabeçalho Authorization ausente ou malformado. O valor do cabeçalho deve ser Bearer seguido de um espaço e da sua chave de API: Authorization: Bearer YOUR-API-KEY. Erros comuns incluem omitir Bearer, omitir a chave depois de Bearer ou colocar o valor entre aspas.- Endpoint REST errado. Você está enviando a solicitação para a instância incorreta. Por exemplo, se sua conta estiver na nossa instância da UE ( https://dashboard-01.braze.eu), a solicitação deve ser enviada para https://rest.fra-01.braze.eu.- Permissões insuficientes. Cada chave de API está vinculada a um espaço de trabalho e a um conjunto de permissões específicos. Verifique as permissões da chave em Configurações > Chaves de API no dashboard. - Chave de API errada. As chaves de API são específicas de cada espaço de trabalho. Uma chave de um espaço de trabalho não pode ser usada para autenticar solicitações de outro espaço de trabalho. |
403 Forbidden |
O plano tarifário não oferece suporte ou a conta está inativa por outro motivo. |
403 Access Denied |
A chave da API REST que você está usando não tem permissões suficientes. As causas mais comuns são:
|
404 Not Found |
URL inválida. |
415 Unsupported Media Type |
O cabeçalho da solicitação Content-Type está ausente ou incorreto. Na página Configurações, adicione Content-Type com o valor application/json. |
429 Rate Limited |
Limite de frequência excedido. |
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 passar 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 incluem 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 de novo:
- Valide a carga útil com um linter de JSON.
- Defina
Content-Type: application/jsone envie JSON codificado em UTF-8. - Confirme se o seu cliente HTTP codifica o objeto em JSON em vez de concatenar strings brutas.
Para o tamanho da carga útil e os limites de objetos por solicitação do /users/track, consulte Por que recebo 400 Bad Request com erro de sintaxe ou de análise?.