Erros & limites

Formato de erro

Toda resposta de erro segue o mesmo envelope JSON:


{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Chave de API inválida, revogada ou expirada.",
  "code": "invalid_api_key"
}

statusCode — o código HTTP.
error — nome curto do erro.
message — mensagem legível (pt-BR).
code — código estável da aplicação, ideal para tratar no seu cliente.

Códigos comuns

Status	`code`	Quando acontece
`400`	`validation_error`	Parâmetros inválidos (veja `issues`)
`401`	`missing_api_key`	Header `Authorization` ausente
`401`	`invalid_api_key`	Chave inválida/revogada/expirada
`403`	`insufficient_scope`	Escopo insuficiente para a operação
`401`	`office_key_required`	Rota `/v1/accounting` chamada com a chave da empresa (`ck_`) — ela exige a chave do escritório (`ok_`)
`403`	`accounting_mode_inactive`	Escritório suspenso — o modo contador não está ativo
`403`	`company_not_in_portfolio`	A empresa não tem vínculo ativo com o escritório
`404`	`not_found`	Recurso não encontrado
`409`	`closing_not_ready`	Download de fechamento que ainda não terminou (ou falhou)
`401`	`invalid_link`	Link de download do ZIP (`/received-documents/export/download`) inválido ou expirado (vale 15 min) — gere outro
`403`	`link_revoked`	A credencial que gerou o link de download perdeu o acesso (chave revogada, acesso desligado, empresa fora da carteira)
`404`	`no_documents`	Download em lote (`/received-documents/export`) de um mês sem nenhum documento recebido
`400`	`portfolio_too_large`	`POST /v1/accounting/closings` ou `GET /v1/accounting/received-documents/export` sem `companyIds` numa carteira com mais de 200 empresas — peça em lotes
`500`	`internal_error`	Erro interno. O detalhe fica no nosso log; o corpo não o expõe
`429`	—	Rate limit excedido
`429`	`sefaz_wait`	`POST /v1/received-documents/sync` dentro da janela de 1h que a SEFAZ exige depois de uma consulta sem novidades — respeite o `Retry-After`
`500`	—	Erro interno

Rate limiting

As requisições são limitadas por chave de API. Ao exceder o limite, a API responde 429 Too Many Requests. Implemente retry com backoff exponencial e respeite os headers de limite quando presentes.

Paginação

Endpoints de listagem aceitam page e pageSize (máx. 100) e retornam:


{
  "data": [ /* ... */ ],
  "meta": { "page": 1, "pageSize": 20, "total": 134, "totalPages": 7 }
}