Erros comuns

Quando algo dá errado, a API não deixa você no escuro: ela responde com um status (um número, como 401) e um código (uma palavra, como invalid_api_key) que dizem o que aconteceu. A mensagem vem em português.

Como é uma resposta de erro

Toda resposta de erro tem este formato:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Chave de API ausente ou inválida. Envie Authorization: Bearer <chave>.",
    "requestId": "req_79399414-c708-4a42-8212-67ae800e5d12"
  }
}

• code: o código do erro. É estável: você pode usá-lo em um fluxo para decidir o que fazer.
• message: a explicação em português.
• details: aparece só em alguns erros, com detalhes extras (por exemplo, quais campos estão errados).
• requestId: o número da chamada. É o que o suporte precisa para achar o que aconteceu. Veja Como achar o requestId.

O exemplo acima é uma chamada feita sem chave.

Tabela de erros

Status	Código	O que significa	Como resolver
400	validation_error	Algum dado da chamada está errado	Corrija o campo indicado em details
400	api_key_in_url	A chave foi enviada no endereço	Tire a chave da URL e use o cabeçalho
400	folder_required	Criar lista sem folderId numa origem sem pasta ou com várias	Informe folderId (veja abaixo)
401	invalid_api_key	Chave ausente ou inválida	Confira a chave e o Bearer
401	api_key_expired	A chave venceu	Crie uma chave nova
401	api_key_revoked	A chave foi revogada	Crie uma chave nova
403	insufficient_scope	A chave é somente leitura e o pedido grava	Use uma chave de leitura e escrita
403	plan_required	A leitura de mídia (GET /ad-metrics, GET /ad-entities) numa conta sem painel de anúncios	Assine o Pro, o Max ou o Agência; os dados ficam guardados
404	not_found	O item não existe nesta conta	Confira o código (id) do item
409	conflict	O pedido bate com algo que já existe	Veja a seção abaixo
409	plan_limit	O limite do plano foi atingido	Mude de plano em Configurações › Cobrança ou libere espaço
409	lead_hidden	O negócio é de um contato oculto, cuja etapa não muda	Mostre o contato na tela antes
413	payload_too_large	O corpo passa de 256 KB (2 MB na mídia de anúncios)	Mande menos dados por chamada
429	rate_limited	Chamadas demais por minuto	Espere o Retry-After
500	internal_error	Erro dentro do CRM	Mande o requestId ao suporte
503	maintenance	CRM só para leitura, por manutenção	Tente de novo em 1 minuto

Os erros que pedem mais explicação estão nas seções a seguir.

validation_error (400)

Quer dizer que a chamada chegou, mas os dados não passam nas regras: um campo obrigatório faltou, um valor passou do tamanho máximo, o JSON está malformado ou você mandou um campo que a API não conhece (no PATCH, isso é sempre erro).

E-mail em formato inválido não dá este erro: o lead é gravado com o e-mail como chegou, e a aba Dados do lead e a lista de leads mostram o aviso de e-mail fora do formato. Quem confere a digitação é o formulário de origem.

Telefone fora do formato também não dá este erro. Com dois números no mesmo campo (por exemplo 11 99999-0000 / 11 98888-0000), vale o primeiro. Sem isso, o telefone com menos de 8 ou mais de 15 dígitos é gravado com os dígitos que vieram e aparece com o aviso de telefone fora do formato. Ele não identifica o lead: dois envios com o mesmo número curto viram dois leads, e a busca por phone não o encontra. Só o telefone sem nenhum dígito, sem e-mail, dá validation_error.

A lista details mostra qual campo e o que está errado. Este é um exemplo (a mensagem exata muda conforme o caso):

{
  "error": {
    "code": "validation_error",
    "message": "Dados inválidos na requisição.",
    "details": [
      {
        "path": "email",
        "message": "E-mail inválido."
      }
    ],
    "requestId": "req_00000000-0000-4000-8000-000000000001"
  }
}

Leia o path (o campo) e corrija o valor. Se a mensagem for “O corpo precisa ser um JSON válido.”, o problema é o texto do corpo: confira aspas, vírgulas e chaves. No PowerShell, veja a dica de aspas em Primeira chamada.

api_key_in_url (400)

A chave nunca pode ir no endereço. Se o texto crm_live_ aparecer na URL, a API recusa a chamada, mesmo que o cabeçalho esteja certo. Tire a chave do endereço e envie só no cabeçalho:

Authorization: Bearer crm_live_SUA_CHAVE_AQUI

Se a chave já foi enviada em uma URL, trate como vazada: revogue e crie outra em Chaves de API.

folder_required (400)

Aparece ao criar uma lista (POST /lists) sem folderId. Sem a pasta, o CRM só escolhe sozinho quando a origem (origin, ou Site se você não mandar) tem uma única pasta. Se a origem não tem nenhuma pasta, crie uma em Leads, na origem certa. Se tem mais de uma, mande o folderId da pasta que você quer: os ids vêm de GET /folders (operação list_folders). A resposta traz em details a origem e quantas pastas ela tem.

Erros 401: a chave não vale

Os três erros 401 têm causas diferentes:

• invalid_api_key: a chave não veio ou não é reconhecida. Confira se copiou a chave inteira, sem espaço sobrando, e se o cabeçalho é Authorization: Bearer seguido da chave.
• api_key_expired: a chave passou da validade. A resposta traz details.expiredAt com o momento em que ela venceu.
• api_key_revoked: alguém revogou a chave na tela Integrações › API.

Nos dois últimos casos, crie uma chave nova e troque na ferramenta. Veja o passo a passo em Chaves de API. Lembre que os gatilhos (webhooks) da chave antiga não passam para a nova: crie-os de novo.

insufficient_scope (403)

A chave é Somente leitura e o pedido tenta criar, alterar ou apagar algo (qualquer chamada que não seja GET, inclusive criar um gatilho). Chaves somente leitura só consultam. Crie uma chave de Leitura e escrita em Chaves de API e troque na ferramenta.

not_found (404)

O lead, a venda, o formulário, a etapa ou o responsável que você citou não existe nesta conta. Quase sempre é um código (id) copiado errado, ou de outra conta. Busque o item de novo pela API (por exemplo, GET /leads) e use o id que ela devolver.

conflict (409)

Existe algo que impede o pedido por já haver outra coisa igual ou em outro estado. Os casos mais comuns:

• você tentou usar um telefone ou e-mail que já pertence a outro lead (um e-mail de contato oculto também conta, e a message avisa; details.hidden vem true);
• o endereço (slug) de um formulário já existe;
• você tentou alterar uma campanha de e-mail que não é mais rascunho;
• a conta já tem o máximo de 50 gatilhos (webhooks).

Leia a message da resposta: ela diz qual é o caso. Troque o dado repetido, ou apague um gatilho que não usa mais.

plan_limit (409)

O plano da conta chegou ao limite de leads ou de vendas. A API não consegue gravar mais até o limite ser ampliado. Chame o suporte para ver as opções.

payload_too_large (413)

O corpo da chamada tem mais de 256 KB. Divida em chamadas menores: por exemplo, em vez de mandar centenas de leads de uma vez, mande um lead por chamada. A gravação de mídia de anúncios (POST /ad-metrics) aceita até 2 MB, para caber o lote de 500 registros; acima disso, mande menos registros por chamada.

rate_limited (429)

Cada chave pode fazer 120 chamadas por minuto. Passou disso, a API responde 429 e diz quanto esperar. Os cabeçalhos da resposta ajudam:

Cabeçalho	O que traz
Retry-After	Quantos segundos esperar antes de tentar de novo
X-RateLimit-Limit	O limite da chave: 120 por minuto
X-RateLimit-Remaining	Quantas chamadas ainda restam neste minuto
X-RateLimit-Reset	Quando a contagem zera, em milissegundos desde 1970

Os três X-RateLimit- vêm nas respostas depois que a chave é aceita. O Retry-After vem no 429.

O que fazer: espere o tempo do Retry-After e tente de novo. Em fluxos que mandam muita coisa de uma vez, faça uma pausa entre as chamadas.

Há um segundo limite: 30 chaves erradas por minuto vindas do mesmo endereço de internet. Passou disso, a resposta também é 429, com a mensagem “Muitas tentativas com chave inválida. Aguarde um minuto.” Confira a chave antes de repetir a chamada.

internal_error (500)

O erro foi do CRM, não da sua chamada. Tente de novo depois de alguns instantes. Se continuar, mande o requestId ao suporte.

maintenance (503)

Durante uma migração, o CRM fica somente para leitura. Nesse período, só as chamadas que gravam (criar, alterar, apagar) recebem este erro; as de leitura continuam funcionando. A resposta traz Retry-After: 60: espere cerca de 1 minuto e tente de novo. Em um fluxo do n8n, ligue a opção de tentar novamente em caso de erro.

Como achar o requestId

O requestId tem o formato req_ seguido de um código, como req_79399414-c708-4a42-8212-67ae800e5d12. Ele aparece em dois lugares de toda resposta:

• no corpo do erro, em error.requestId;
• no cabeçalho X-Request-Id.

1. No curl, veja o corpo. O requestId está na resposta que aparece no terminal. Para ver também os cabeçalhos, acrescente -i ao comando.

2. No n8n, abra a saída de erro do nó. Se o nó HTTP Request falhar, clique nele e abra a aba de saída (Output) ou o erro. O requestId aparece dentro do corpo do erro. Se você ligou a opção de mostrar a resposta completa, o cabeçalho X-Request-Id também aparece.

3. Copie e envie ao suporte. Fale com o suporte e mande o requestId, o horário aproximado e o que você estava tentando fazer. Nunca envie a sua chave de API.

Com o requestId, a equipe encontra a chamada exata nos registros do CRM.