Erros

Todos os erros seguem o mesmo formato JSON. O campo code é estável e pode ser tratado programaticamente; message é legível por humanos (PT-BR).

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_API_CREDENTIALS",
    "message": "Credenciais de API inválidas.",
    "details": null
  }
}

Códigos HTTP e de negócio

HTTP	code	Descrição
`400`	`MISSING_API_KEY`	Header X-Api-Key ausente
`400`	`MISSING_API_SECRET`	Header X-Api-Secret ausente
`400`	`MISSING_COMPANY_ID`	companyId ausente no path
`400`	`INVALID_COMPANY_ID`	companyId do path não é UUID válido
`401`	`INVALID_API_CREDENTIALS`	Chave ou secret inválidos
`402`	`SUBSCRIPTION_REQUIRED`	Assinatura em atraso ou suspensa
`402`	`ACCOUNT_SUBSCRIPTION_REQUIRED`	Assinatura da conta não encontrada
`403`	`COMPANY_ACCESS_DENIED`	Usuário sem acesso à empresa do path
`404`	`COMPANY_NOT_FOUND`	Empresa não encontrada
`404`	`INVOICE_NOT_FOUND`	Nota fiscal não encontrada
`409`	`COMPANY_ALREADY_EXISTS`	CNPJ já cadastrado nesta conta
`422`	`VALIDATION_ERROR`	Corpo da requisição inválido (Zod)
`422`	`INVALID_INVOICE_STATUS`	Operação não permitida para este status
`429`	`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido (conforme o plano)

Erros de validação

Erros de validação do corpo da requisição (Zod) retornam 422 com code: VALIDATION_ERROR. Os campos inválidos ficam em error.details.fields.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
    "details": {
      "fields": [
        {
          "field": "borrower.name",
          "error": "String must contain at least 1 character(s)"
        }
      ]
    }
  }
}