Entender o erro

Pro e FullAtualizado em 13/10/2026

A API responde com código HTTP e um JSON com message. A tabela abaixo cobre o que aparece de verdade no dia a dia.

Código	Quer dizer	Causa mais comum	O que fazer
`200` / `201`	Deu certo		Leia o corpo da resposta
`400`	Pedido mal formado	JSON inválido, campo com tipo errado, falta `locationId`, falta o header `Version`	Leia o `message`: ele lista o campo. Confira o header `Version: 2021-07-28`
`401`	Não autenticado	Token errado, revogado, expirado por 90 dias sem uso, ou com espaço sobrando	Copie o token de novo. Se foi apagado, crie outro
`401` com menção a escopo	Token válido, mas sem permissão pra essa área	Faltou marcar o escopo	Edite os escopos
`403`	Proibido	Tentando acessar uma conta que não é a do token	Confira o `locationId`
`404`	Não existe	Id de contato, oportunidade ou pipeline errado, ou de outra conta	Busque o id de novo pela listagem
`422`	Não processável	Dados válidos em forma, inválidos em conteúdo: telefone que não é telefone, e-mail repetido quando não pode, fase que não pertence ao pipeline	Leia o `message` e corrija o dado
`429`	Limite de chamadas	Passou de 100 em 10 segundos ou de 200 mil no dia	Espere e tente de novo com intervalo crescente. Veja Limites de uso
`500` / `502` / `503`	Erro do lado da plataforma	Instabilidade momentânea	Tente de novo em alguns segundos, até 3 vezes. Se persistir por minutos, avise o suporte

Como ler o corpo do erro

{
  "statusCode": 422,
  "message": ["phone must be a valid phone number"],
  "error": "Unprocessable Entity"
}

message pode ser texto ou lista. Em 400 e 422 ele sempre aponta o campo. Registre o corpo inteiro no seu log, e não só o código: é o que o suporte vai pedir.

Erros que não são erros

Lista vazia com 200: o filtro não bateu nada. locationId de outra conta também dá lista vazia, não 404.
Upsert devolvendo o mesmo contato: era pra ser. Veja Criar ou atualizar contato sem duplicar.
Telefone devolvido diferente do enviado: a plataforma normaliza pro formato internacional (+5524...). Guarde o que ela devolve.

Padrão de tratamento no código

const r = await fetch(url, opcoes);
if (r.status === 429) return tentarDeNovoDepois(r);
if (r.status >= 500) return tentarDeNovoDepois(r, 3);
if (!r.ok) { const erro = await r.json(); throw new Error(`${r.status}: ${JSON.stringify(erro.message)}`); }
return r.json();

Erro 4xx que não é 429 não se resolve tentando de novo. Corrija o dado ou o token.

Antes de chamar o suporte

Tenha em mãos: o endpoint, o corpo enviado (sem o token), o código e o corpo da resposta, e o horário. Com isso a resposta sai na primeira mensagem. O que o suporte cobre está em Até onde o suporte vai.