Fundamentos

Erros

Status HTTP convencionais e um corpo de erro sempre no mesmo formato, com mensagem em português.

Formato

422

{
  "error": {
    "code": "VALIDATION",
    "message": "Confira os campos destacados.",
    "fields": { "customer.document": "CPF/CNPJ inválido" },
    "errorId": "req_4f1c0a9e2b7d4c1e8a3b"
  }
}

O errorId é o mesmo valor do cabeçalho x-request-id. Mensagens nunca expõem detalhes internos.

Códigos

VALIDATION422Corpo ou parâmetros inválidos. Veja fields para o motivo de cada campo.

UNAUTHORIZED401Chave ausente, inválida ou revogada.

NO_PERMISSION403A chave não tem o escopo exigido.

ACCOUNT_NOT_APPROVED403Empresa em análise — use o Sandbox até a aprovação.

ACCOUNT_SUSPENDED403Conta suspensa. Operações financeiras bloqueadas.

FEATURE_DISABLED403O produto não está ativo para a empresa (ative em Catálogo).

NOT_FOUND404Recurso ou rota inexistente — ou de outro ambiente.

CONFLICT409Estado não permite a operação (ex.: cancelar cobrança já paga).

IDEMPOTENCY_IN_PROGRESS409Requisição com a mesma Idempotency-Key ainda em andamento.

IDEMPOTENCY_MISMATCH422Idempotency-Key reutilizada com outro corpo.

RATE_LIMITED429Muitas requisições. Aguarde e tente de novo com backoff.

PROVIDER_UNAVAILABLE503Parceiro de liquidação indisponível no momento. Pode repetir (com a mesma Idempotency-Key).

NOT_CONFIGURED503Integração do parceiro ainda não configurada para esta operação.

INTERNAL500Erro inesperado do nosso lado. Informe o errorId ao suporte.

Quando repetir

Repita com backoff exponencial apenas 429, 5xx e falhas de rede — sempre com a mesma Idempotency-Key nas rotas financeiras. Erros 4xx exigem correção da requisição.