Erros
O formato das respostas de erro, os status HTTP e como decidir o que fazer pelo code.
Quando uma chamada não pode ser atendida, a API responde com um status HTTP de erro e um corpo JSON. Decida o que fazer pelo status e, quando houver, pelo code. A message é um texto para pessoas: pode estar em português ou em inglês e pode mudar sem aviso.
Formato
{
"error": true,
"code": "read_permission_required",
"message": "Insufficient permissions: requires leads:read in this workspace",
"expected": {
"required_permission": "leads:read"
}
}| Campo | Descrição |
|---|---|
error | Sempre true em uma resposta de erro. |
code | Identificador estável do erro. Presente na maioria das rotas; algumas recusas antigas, como as de token inválido, não têm code. |
message | Explicação para registro e suporte. Não compare este texto no seu código. |
expected | Presente em algumas recusas, com o nome de cada campo e o que se esperava dele, por exemplo {"email": "string (required)"}. |
optional | Presente em algumas recusas de validação, com os campos opcionais aceitos. |
details | Presente em alguns erros, com dados para a próxima tentativa, como retry_after_seconds ou maxBytes. |
Os códigos que cada rota devolve estão na descrição dela, na Referência da API. Os códigos da API de e-mail transacional estão em API de e-mail transacional.
Exceções ao formato
- Conflito de versão. Rotas que editam com o cabeçalho
If-Matchrespondem409com{"code": "version_conflict", "message": "...", "current": ...}, em quecurrenté a versão atual do recurso. Sem oIf-Match, respondem428com o códigoversion_required. - Algumas rotas (WebChat, caixas de e-mail e o envio rápido de campanhas de WhatsApp) devolvem o código no próprio campo
error:{"error": "invalid_body", "message": "..."}.
Status HTTP
| Status | Significado | O que fazer |
|---|---|---|
200 | Sucesso. | |
201 | Recurso criado. | |
202 | Pedido aceito para processamento em segundo plano. | Acompanhe pelo recurso devolvido. |
204 | Sucesso, sem corpo. | |
400 | Um campo está ausente ou inválido, ou o corpo não é um JSON válido. | Corrija antes de repetir. |
401 | Credencial ausente, inválida, expirada ou encerrada. | Renove o token ou faça login de novo. Veja Autenticação. |
402 | Saldo insuficiente ou plano sem o recurso. | Resolva no workspace antes de repetir. |
403 | Sem permissão no workspace, ou fora do departamento. | Não repita; ajuste as permissões do usuário. |
404 | O recurso não existe neste workspace. | Confira o id e o X-Workspace-ID. |
409 | Conflito com o estado atual do recurso. | Leia o recurso de novo e decida. |
413 | O corpo passa do tamanho permitido. | Reduza o corpo. |
422 | O pedido está bem formado, mas o conteúdo não pode ser aceito. | Corrija o conteúdo. |
428 | Falta o cabeçalho If-Match com a versão. | Envie a versão carregada. |
429 | Limite de requisições atingido. | Aguarde e repita. Veja Limites de requisição. |
500 | Erro inesperado. | Repita mais tarde; se persistir, fale com o suporte. |
502 | Um serviço externo (por exemplo, um provedor de mensagens) recusou ou falhou. | Repita mais tarde. |
503 | Um serviço necessário está indisponível naquele momento. | Repita mais tarde, respeitando Retry-After quando vier. |
Como tratar
- Use o
codequando ele existir. Ele não muda, e é ele que diferencia, por exemplo, dois409diferentes. 400,403,404,413e422: não repita a mesma requisição sem corrigir a causa.401: renove o token uma vez e repita. Se falhar de novo, faça login.429e503: espere antes de repetir. Quando houver o cabeçalhoRetry-After, espere os segundos indicados.500,502e falhas de rede: repita com espera crescente. Em rotas que geram envio ou cobrança, repita só se a rota aceitar uma chave de idempotência. Veja Idempotência.
Updated 17 days ago
Did this page help you?