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 مشوه أو معرّف غير رقمي؛ تذكر الرسالة الحقل.
401	بلا مفتاح أو مفتاح غير صالح.
403	المفتاح لا يملك هذا النطاق (مثل الكتابة بمفتاح قراءة فقط) أو المورد معطل في الحساب.
404	مورد أو معرّف غير موجود — تسرد الاستجابة الموارد المتاحة.
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.