Erros, paginação e limites

Todo endpoint de dados responde erros no mesmo envelope. Apenas erros processados pelo POST /oauth/token usam o formato OAuth; métodos inválidos e rotas desconhecidas usam o envelope global.

Convenções gerais

Todas as respostas usam application/json; charset=utf-8 e não são armazenadas em cache.
Parâmetros de consulta desconhecidos ou repetidos retornam 400 requisicao_invalida; envie cada parâmetro uma única vez.
Datas de filtro usam YYYY-MM-DD. Campos de data de negócio usam esse mesmo formato; campos datetime usam RFC 3339 em UTC. Períodos são interpretados em America/Sao_Paulo.
Valores monetários e quantidades são números JSON, não strings formatadas em moeda.
Rotas de dados aceitam somente os métodos documentados. Não há endpoints de criação, alteração ou exclusão de dados na v1.

Envelope de erro

{
  "erro": {
    "codigo": "requisicao_invalida",
    "mensagem": "Um ou mais parâmetros são inválidos.",
    "detalhes": [
      { "campo": "data_fim", "mensagem": "Informe junto com data_inicio." }
    ],
    "request_id": "9bde2aa8-56c4-4ce8-9571-a55e45410c86"
  }
}

HTTP	Código	Causa típica
400	requisicao_invalida	Parâmetro, filtro, data ou ordenação inválida.
401	token_invalido	Bearer ausente, inválido, revogado ou expirado.
403	escopo_insuficiente	Escopo exato da operação ausente no token.
403	ip_nao_autorizado	IP fora da allowlist configurada na credencial.
404	recurso_nao_encontrado	ID inexistente (ou pertence a outra empresa).
405	metodo_nao_permitido	Método HTTP não suportado nessa rota.
413	corpo_muito_grande	Corpo acima de 8 KiB; aplicável ao `POST /oauth/token`.
415	tipo_conteudo_invalido	Content-Type diferente de `application/x-www-form-urlencoded` no `POST /oauth/token`.
429	limite_excedido	Rate limit excedido (ver abaixo).
500	erro_interno	Falha inesperada — sem detalhe interno na resposta.
503	servico_indisponivel	Banco do tenant ou central indisponível.

Headers adicionais por situação

Situação	Header	Uso
Token ausente ou inválido	`WWW-Authenticate: Bearer ...`	Indica que um Bearer token válido deve ser enviado.
Escopo insuficiente	`WWW-Authenticate: Bearer ... scope="..."`	Informa o escopo exigido pela rota.
Método não permitido	`Allow`	Lista os métodos aceitos na rota.
Rate limit excedido	`Retry-After`	Segundos até tentar novamente.

Headers

Toda resposta inclui:

Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Pragma: no-cache
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
X-Request-ID: <uuid>

Respostas autenticadas somam:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1786057200

Você pode mandar seu próprio X-Request-ID — se for um UUID válido, é reaproveitado na resposta; caso contrário, um novo é gerado.

Paginação

Parâmetro	Regra
pagina	Inteiro ≥ 1. Padrão `1`.
por_pagina	Inteiro entre 1 e 200. Padrão `50`.
ordenar_por	Campo permitido — varia por recurso, ver a página de cada endpoint.
ordem	`asc` ou `desc`.

{
  "data": [ ],
  "meta": {
    "pagina": 1,
    "por_pagina": 50,
    "total": 0,
    "total_paginas": 0
  }
}

Períodos

Endpoints com data_inicio/data_fim (ordens de serviço, contas a receber/pagar, boletos) seguem sempre a mesma regra:

os dois parâmetros são obrigatórios juntos;
formato YYYY-MM-DD, limites inclusivos;
não aceitam datas inexistentes (ex.: 2026-02-30);
não aceitam data_inicio > data_fim;
intervalo máximo de 12 meses;
interpretados no fuso America/Sao_Paulo.

Rate limit

Janela fixa de 1 minuto, por credencial: 120 requisições/minuto nos endpoints de dados. O endpoint de token tem limites próprios (ver Autenticação).

Ao estourar o limite, a resposta é 429 limite_excedido com header Retry-After (segundos até a próxima janela):

{
  "erro": {
    "codigo": "limite_excedido",
    "mensagem": "Limite de requisições excedido.",
    "detalhes": [],
    "request_id": "3b1a2c4d-..."
  }
}