Erros

Toda mensagem que a API devolve, com o motivo e o que fazer.

Formato

Todo erro volta em JSON com o campo erro, em português, legível por pessoa. Alguns trazem campos de apoio: recursos (o que existe), dica, exemplo, codigo (para tratar por programa) e comoResolver.

401 · application/json

{"erro":"chave de API ausente ou inválida"}

Atenção: nas leituras de lista e em /me, uma falha de parâmetro (desde ou depoisDe inválido) ou de consulta volta com status 200 e o campo erro no corpo. Confira se a resposta tem erro antes de ler data.

Códigos de status

HTTP	Descrição
400	不正なリクエスト — JSONの不備または数値でないid。メッセージがフィールドを示します。
401	キーがない、または無効。
403	キーにそのスコープがない（例：読み取り専用キーでの書き込み）か、リソースがアカウントで無効。
404	リソースまたはidが存在しない — 応答に利用可能なリソース一覧が含まれます。
409	キーに責任ユーザーがいない — 作成者を付けるため責任ユーザー付きで作り直してください。
429	毎分の制限超過 — Retry-Afterを待ってください。

Catálogo completo

HTTP	Mensagem (campo erro)	Quando acontece
200, com erro no corpo	`parâmetro 'desde' inválido — use 2026-08-27 ou 2026-08-27T14:30:00`	O parâmetro desde não é data nem data e hora. Vem com status 200.
200, com erro no corpo	`parâmetro 'depoisDe' inválido — use o proximoId da resposta anterior`	O parâmetro depoisDe não é número. Vem com status 200.
200, com erro no corpo	`falha ao consultar`	A consulta falhou do nosso lado. Vem com status 200; repita mais tarde e, persistindo, veja a página de status.
200, com erro no corpo	`não foi possível carregar o tenant`	Não foi possível ler a conta. Vem com status 200.
207 · resultados[].erro	`nome é obrigatório`	Lote de clientes ou leads: faltou nome, ou veio vazio (o item volta com status erro).
207 · resultados[].erro	`titulo é obrigatório`	Lote de demandas: faltou titulo, ou veio vazio (o item volta com status erro).
207 · resultados[].erro	`clienteId não existe nesta empresa`	Lote de demandas: o clienteId não pertence à conta (o item volta com status erro).
207 · resultados[].erro	`tipoId não existe nesta empresa`	Lote de demandas: o tipoId não pertence à conta (o item volta com status erro).
207 · resultados[].erro	`contratoId não existe nesta empresa`	Lote de demandas: o contratoId não pertence à conta (o item volta com status erro).
400	`Idempotency-Key é obrigatória em escrita desde 2026-12-01 (aviso publicado em 2026-09-01): sem ela, um retry de rede cria o registro duas vezes. Envie um valor único por operação no cabeçalho Idempotency-Key.`	Escrita sem Idempotency-Key depois da data de obrigatoriedade.
400	`JSON inválido`	O corpo não é um objeto JSON válido.
400	`lote vazio`	O lote veio sem nenhum item.
400	`envie um array de itens: [{...}] ou {"itens":[{...}]}`	O corpo não é um array de itens nem um objeto com itens.
400	`id inválido`	O id do endereço não é número.
400	`informe o dataset`	Faltou a chave do conjunto de dados no endereço.
401	`chave de API ausente ou inválida`	Sem cabeçalho de chave, chave revogada ou digitada errada.
401	`chave sem empresa vinculada`	A chave existe mas não está ligada a uma conta. Gere outra em Configurações › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	A chamada veio para a conta de demonstração: lá a API pública fica desligada.
403	`identidade da chave de API irregular`	A conta recusa chaves com identidade irregular (pessoa desligada ou chave sem dono). O corpo traz motivo e comoResolver.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Escrita com chave de escopo somente leitura.
403	`o log de alterações via API está desligado nesta conta (parâmetro API.LOG_ALTERACOES_ATIVO)`	A conta desligou o log de alterações via API. A trilha continua gravada e visível na tela.
404	`recurso sem trilha de alterações`	O recurso não tem trilha de alterações. A resposta lista os que têm.
404	`dataset não encontrado: {dataset}`	O conjunto de dados não existe ou não está disponível para a conta. Consulte o catálogo.
405	`método não suportado (use GET, POST, PUT, PATCH ou DELETE)`	Método HTTP que a API não atende.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	A chave de escrita não tem usuário responsável: sem autoria, nada é gravado.
409	`Idempotency-Key já usada com um corpo DIFERENTE — gere uma chave nova por operação`	A mesma Idempotency-Key veio com outro corpo.
409	`requisicao com esta Idempotency-Key ainda em processamento — aguarde e repita`	A mesma Idempotency-Key chegou enquanto a primeira chamada ainda rodava. Repita depois do Retry-After.
413	`lote com {n} itens; o teto é 200 por chamada`	O lote passou do teto de itens por chamada.
422	`nome é obrigatório`	Faltou nome, ou veio vazio.
422	`não foi possível criar: {detalhe}`	A gravação foi recusada (por exemplo, valor maior que o campo aceita). O detalhe vem na mensagem.
429	`limite de requisições excedido (120/min)`	Passou do limite por minuto da chave. Espere o Retry-After.
500	`a consulta não rodou`	A consulta analítica falhou. Tente menos colunas ou outro filtro.