Confido Docs

Erros

O formato do erro, os códigos estáveis e o que fazer com cada status HTTP.

Todo erro vem com o status HTTP certo e um corpo JSON no mesmo formato:

{
  "statusCode": 422,
  "timestamp": "2026-11-03T18:00:00Z",
  "path": "/api/v1/charges",
  "code": "validation_error",
  "message": "dueDate deve ser uma data AAAA-MM-DD",
  "field": "dueDate"
}
Campo O que é
statusCode O mesmo status HTTP da resposta.
timestamp Quando o erro aconteceu (UTC).
path A rota chamada.
code Código estável, para o seu código tratar o erro sem depender do texto.
message Explicação em português, para pessoas. Pode mudar: não compare o texto.
field O primeiro campo com problema, quando há um.
fields Todos os campos com problema e o motivo de cada um: { "payer.document": "CPF/CNPJ inválido" }.
error Às vezes vem também o nome do status ("Forbidden"). Trate pelo code.

Diferenças nas vendas (/payments e /card-tokens)

As rotas de venda usam o mesmo formato, com três diferenças:

  • code vem só quando existe um código estável para o caso (por exemplo store_required ou amount_below_fees). Sem code, trate pelo status HTTP.
  • Não existe field: os campos vêm sempre em fields. Nas checagens básicas (tipo, obrigatório, tamanho), a chave do campo vem em minúsculas (amountcents, expyear); nas do pagador, com o caminho completo (payer.address.zipCode).
  • Com code: "amount_below_fees", o campo min_amount_cents diz o menor valor aceito para aquela venda.
code Status Quer dizer
missing_api_key 401 Faltou o cabeçalho X-API-Key.
invalid_api_key, api_key_revoked, api_key_expired 401 A chave não existe, foi revogada ou venceu.
ip_not_allowed 403 O IP que chamou não está na lista da chave.
insufficient_scope 403 A chave não tem o escopo da rota.
connect_not_enabled 403 Subcontas: o Connect ainda não foi liberado para a conta. Solicite em Configurações do negócio, no painel, e espere a aprovação.
connect_not_available 403 Subcontas: conta de pessoa física (CPF) não tem Connect.
forbidden 403 A conta não pode fazer isso (por exemplo, conta não aprovada).
invalid_request, validation_error 400 O pedido está malformado ou algum campo é inválido.
not_found 404 Não existe nesta conta (ou é de outra conta).
conflict 409 O estado atual não permite (por exemplo, encerrar subconta com saldo).
idempotency_key_reused 409 A Idempotency-Key já foi usada com outro corpo.
idempotency_request_in_progress 409 A primeira chamada com essa chave ainda está rodando.
unprocessable_entity 422 Os dados são válidos, mas a regra de negócio recusou.
payload_too_large 413 O corpo passou do tamanho máximo.
rate_limited 429 Passou do limite por minuto (veja Retry-After).
internal_error 500 Erro do nosso lado. Pode repetir com a mesma chave de idempotência.
service_unavailable 503 Serviço indisponível por instantes. Repita em seguida.

Recusa não é erro

Uma venda recusada pelo banco não é erro HTTP: a criação responde 201 com status: "declined" e o motivo em failureCode e failureMessage (por exemplo insufficient_funds ou 3ds_failed). Quando o problema é nosso ou da rede, o status vem failed e o failureCode, processing_failed.

Para tentar de novo uma venda declined ou failed, mande uma nova idempotencyKey (por exemplo pedido-42-tentativa-2): a mesma chave devolveria a venda que já falhou.

Veja também Idempotência para saber quando repetir.