Respostas e erros

Envelope

Toda resposta, de sucesso ou de erro, vem no mesmo envelope JSON:

Campo	Tipo	Descrição
message	string	Mensagem curta: o nome da operação no sucesso, o motivo no erro.
result	boolean	true no sucesso, false no erro.
data	objeto ou null	O conteúdo da resposta. null no erro.
error	string ou null	O motivo do erro. null no sucesso.

Sucesso:

{
  "message": "Pedido recebido",
  "result": true,
  "data": { "status": "RECEIVED" },
  "error": null
}

Erro:

{
  "message": "page_size must not be greater than 1000",
  "result": false,
  "data": null,
  "error": "page_size must not be greater than 1000"
}

observação

Isso vale também para POST /oauth/token: o token fica em data, e não na raiz do JSON como no formato puro do OAuth 2.0 (RFC 6749). Se a sua biblioteca de OAuth espera o formato puro, leia data.access_token você mesmo.

Códigos HTTP

Código	Quando acontece	O que fazer
200	Consulta ou emissão de token com sucesso.
202	Pedido de acesso ou reemissão recebido.	Consulte a situação depois.
400	Parâmetro inválido: campo a mais, formato errado, page ou page_size fora do limite, date_from ou date_to antes de 90 dias atrás, etc. A mensagem diz o motivo.	Corrija a chamada. Não repita igual.
401	Não autorizado. Credencial errada, token vencido ou revogado, company_token inválido. A resposta nunca diz qual parte falhou.	Veja Quando dá 401.
403	Token sem permissão para a rota.	Fale com o Concilia+.
404	Rota inexistente.	Confira o caminho.
413	Corpo da requisição acima de 10 kB.	Nenhuma rota precisa de corpo grande: confira o que está sendo enviado.
429	Limite de uso excedido. Vem com o header Retry-After (em segundos).	Espere o tempo do Retry-After e tente de novo. Veja Limites de uso.
500	Erro interno.	Tente de novo mais tarde, com espera crescente.
503	Serviço temporariamente indisponível. Só no POST /oauth/token.	Tente de novo em alguns segundos. Tokens já emitidos continuam valendo.

Validação dos parâmetros

• Campos que a rota não conhece são recusados com 400, não ignorados. Envie só o que está documentado.
• Os formatos são conferidos com rigor: client_id, client_secret, company_token, CNPJ e datas. Exemplo: client_id sempre começa com ci_ e tem 25 caracteres.
• As mensagens de erro de formato dos campos vêm em inglês (por exemplo, page_size must not be greater than 1000), separadas por ; quando há mais de uma. As regras entre campos e de datas vêm em português (por exemplo, date_from deve ser menor ou igual a date_to). Não dependa do texto: trate pelo código HTTP.

Formatos dos dados

Tipo	Formato	Exemplo
Data e hora	ISO 8601 em UTC	2026-10-21T14:30:45.000Z
updated_at dos feeds	ISO 8601 em UTC, com microssegundos	2026-10-02T06:15:03.482915Z
Data	YYYY-MM-DD	2026-10-01
Hora	HH:MM:SS	14:22:05
Valores em reais	Texto decimal, com ponto e 6 casas	"150.000000"
Ids	Texto	"84213"

:::tip Valores em reais Os valores vêm como texto para não perder precisão. Converta para um tipo decimal do seu sistema; não use ponto flutuante (float/double). :::