Errors

Every message the API returns, with the reason and what to do.

Format

Every error comes back as JSON with an erro field, in Portuguese, human readable. Some add helper fields: recursos (what exists), dica, exemplo, codigo (for programmatic handling) and comoResolver.

401 · application/json

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

Heads-up: on list reads and on /me, a parameter failure (invalid desde or depoisDe) or a query failure comes back with status 200 and the erro field in the body. Check for erro before reading data.

Status codes

HTTP	Description
400	invalid request — malformed JSON or non-numeric id; the message names the field.
401	no key or invalid key.
403	the key lacks that scope (e.g. writing with a read-only key) or the resource is switched off in the account.
404	resource or id does not exist — the response lists the available resources.
409	the key has no responsible user; recreate it with one so the change has authorship.
429	per-minute limit exceeded — wait the Retry-After.

Full catalog

HTTP	Message (erro field)	When it happens
200, with erro in the body	`parâmetro 'desde' inválido — use 2026-08-27 ou 2026-08-27T14:30:00`	desde is neither a date nor a date-time. Comes with status 200.
200, with erro in the body	`parâmetro 'depoisDe' inválido — use o proximoId da resposta anterior`	depoisDe is not a number. Comes with status 200.
200, with erro in the body	`falha ao consultar`	The query failed on our side. Comes with status 200; retry later and, if it persists, check the status page.
200, with erro in the body	`não foi possível carregar o tenant`	The account could not be read. Comes with status 200.
207 · resultados[].erro	`nome é obrigatório`	Customer or lead batch: nome missing or empty (the item comes back with status erro).
207 · resultados[].erro	`titulo é obrigatório`	Ticket batch: titulo missing or empty (the item comes back with status erro).
207 · resultados[].erro	`clienteId não existe nesta empresa`	Ticket batch: clienteId does not belong to the account (the item comes back with status erro).
207 · resultados[].erro	`tipoId não existe nesta empresa`	Ticket batch: tipoId does not belong to the account (the item comes back with status erro).
207 · resultados[].erro	`contratoId não existe nesta empresa`	Ticket batch: contratoId does not belong to the account (the item comes back with 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.`	Write without Idempotency-Key after the mandatory date.
400	`JSON inválido`	The body is not a valid JSON object.
400	`lote vazio`	The batch has no items.
400	`envie um array de itens: [{...}] ou {"itens":[{...}]}`	The body is neither an array of items nor an object with itens.
400	`id inválido`	The id in the URL is not a number.
400	`informe o dataset`	The dataset key is missing from the URL.
401	`chave de API ausente ou inválida`	No key header, revoked key or typo.
401	`chave sem empresa vinculada`	The key exists but is not linked to an account. Create another one in Settings › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	The call reached the demo account, where the public API is turned off.
403	`identidade da chave de API irregular`	The account refuses keys with irregular identity (deactivated person or ownerless key). The body brings motivo and comoResolver.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Write with a read-only key.
403	`o log de alterações via API está desligado nesta conta (parâmetro API.LOG_ALTERACOES_ATIVO)`	The account turned off the API change log. The trail is still recorded and visible on screen.
404	`recurso sem trilha de alterações`	The resource has no change trail. The response lists those that do.
404	`dataset não encontrado: {dataset}`	The dataset does not exist or is not available to the account. Check the catalog.
405	`método não suportado (use GET, POST, PUT, PATCH ou DELETE)`	HTTP method the API does not serve.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	The write key has no responsible user: without authorship nothing is saved.
409	`Idempotency-Key já usada com um corpo DIFERENTE — gere uma chave nova por operação`	The same Idempotency-Key came with another body.
409	`requisicao com esta Idempotency-Key ainda em processamento — aguarde e repita`	The same Idempotency-Key arrived while the first call was still running. Retry after Retry-After.
413	`lote com {n} itens; o teto é 200 por chamada`	The batch exceeds the per-call item ceiling.
422	`nome é obrigatório`	nome is missing or empty.
422	`não foi possível criar: {detalhe}`	The write was refused (for example, a value longer than the field allows). Details in the message.
429	`limite de requisições excedido (120/min)`	The key went over its per-minute limit. Wait for Retry-After.
500	`a consulta não rodou`	The analytics query failed. Try fewer columns or another filter.