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"
  }
}
CampoDescrição
errorSempre true em uma resposta de erro.
codeIdentificador estável do erro. Presente na maioria das rotas; algumas recusas antigas, como as de token inválido, não têm code.
messageExplicação para registro e suporte. Não compare este texto no seu código.
expectedPresente em algumas recusas, com o nome de cada campo e o que se esperava dele, por exemplo {"email": "string (required)"}.
optionalPresente em algumas recusas de validação, com os campos opcionais aceitos.
detailsPresente 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-Match respondem 409 com {"code": "version_conflict", "message": "...", "current": ...}, em que current é a versão atual do recurso. Sem o If-Match, respondem 428 com o código version_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

StatusSignificadoO que fazer
200Sucesso.
201Recurso criado.
202Pedido aceito para processamento em segundo plano.Acompanhe pelo recurso devolvido.
204Sucesso, sem corpo.
400Um campo está ausente ou inválido, ou o corpo não é um JSON válido.Corrija antes de repetir.
401Credencial ausente, inválida, expirada ou encerrada.Renove o token ou faça login de novo. Veja Autenticação.
402Saldo insuficiente ou plano sem o recurso.Resolva no workspace antes de repetir.
403Sem permissão no workspace, ou fora do departamento.Não repita; ajuste as permissões do usuário.
404O recurso não existe neste workspace.Confira o id e o X-Workspace-ID.
409Conflito com o estado atual do recurso.Leia o recurso de novo e decida.
413O corpo passa do tamanho permitido.Reduza o corpo.
422O pedido está bem formado, mas o conteúdo não pode ser aceito.Corrija o conteúdo.
428Falta o cabeçalho If-Match com a versão.Envie a versão carregada.
429Limite de requisições atingido.Aguarde e repita. Veja Limites de requisição.
500Erro inesperado.Repita mais tarde; se persistir, fale com o suporte.
502Um serviço externo (por exemplo, um provedor de mensagens) recusou ou falhou.Repita mais tarde.
503Um serviço necessário está indisponível naquele momento.Repita mais tarde, respeitando Retry-After quando vier.

Como tratar

  • Use o code quando ele existir. Ele não muda, e é ele que diferencia, por exemplo, dois 409 diferentes.
  • 400, 403, 404, 413 e 422: 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.
  • 429 e 503: espere antes de repetir. Quando houver o cabeçalho Retry-After, espere os segundos indicados.
  • 500, 502 e 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.

Did this page help you?