Erros

Todo erro da API segue o mesmo formato:

{
  "error": {
    "code": "ACCOUNT_NOT_VERIFIED",
    "message": "The account must be verified before it can operate",
    "fields": {
      "amountCents": ["must be greater than or equal to 80"]
    },
    "requestId": "req_8f2c1a..."
  }
}

string

Código estável para tratamento programático — use este campo na sua lógica, não a mensagem.

string

Descrição legível do erro, em inglês.

object

Sempre presente no envelope. Vem vazio ({}) na maioria dos erros; só é preenchido, campo por campo, quando o corpo da requisição falha na validação (422 VALIDATION_ERROR).

string

Identificador único da requisição. Envie para o suporte ao relatar um problema.

Erros comuns

HTTP	Código	Causa
`400`	`IDEMPOTENCY_KEY_REQUIRED`	O cabeçalho `Idempotency-Key` não foi enviado.
`401`	`INVALID_API_KEY`	Chave de API ausente, inválida, revogada ou expirada.
`403`	`ACCOUNT_NOT_VERIFIED`	A conta ainda não foi verificada.
`403`	`INSUFFICIENT_SCOPE`	A chave de API usada não tem o escopo necessário para essa chamada (`pix:read`, `pix:write` ou `balance:read`).
`404`	`CHARGE_NOT_FOUND`	Nenhuma cobrança com esse `id` foi encontrada na sua conta.
`409`	`IDEMPOTENCY_KEY_REUSED`	O cabeçalho `Idempotency-Key` já foi usado com um corpo diferente.
`409`	`PAYOUTS_PAUSED`	Saques estão temporariamente pausados na plataforma.
`422`	`VALIDATION_ERROR`	O corpo da requisição não passou na validação — confira `fields` para saber qual campo.
`422`	`FEE_EXCEEDS_AMOUNT`	A taxa calculada seria maior ou igual ao valor da cobrança.
`422`	`PIX_KEY_REQUIRED`	Nenhuma chave Pix de saque cadastrada na conta.

Sempre confira o requestId ao investigar um erro — ele identifica a requisição exata nos nossos logs.

Introdução

Cobranças

Saldo

Webhooks

Erros

Erros comuns

​Erros comuns

Erros comuns