Começar

Erros

Todo erro volta com o mesmo formato: uma message legível em português, um code estável para o seu código decidir o que fazer e, nos erros de campo, errors com o caminho de cada campo.

Formato

Os caminhos seguem o corpo enviado: customer.email, items.0.pix.key.

1{2  "message": "Dados inválidos",3  "code": "validation_error",4  "errors": {5    "customer.email": [6      "O campo e-mail do cliente deve ser um endereço de e-mail válido."7    ]8  }9}

Códigos

validation_error: 422. Campo ausente ou inválido; detalhes em errors.
idempotency_key_required: 422. POST /charges sem o header Idempotency-Key.
reference_required: 422. Saque ou pré-aprovação sem reference e sem Idempotency-Key.
duplicate_reference: 409. A reference já foi usada; a resposta traz o registro existente em payout ou pre_approval.
request_in_progress: 409. Outro saque da conta está sendo processado agora; tente de novo em instantes.
limit_exceeded: 422. Limite de saque atingido. reason diz qual (daily_count_reached, daily_amount_reached, daily_amount_left, per_cashout_amount_exceeded, settlement_hold) e context traz os números.
processor_rejected: 422. O processador recusou o saque na hora; processor_status traz o status recebido. Nada foi debitado.
recipient_tax_id_required: 422. A conta exige recipient.tax_id no saque e ele não foi enviado.
recipient_tax_id_invalid: 422. O recipient.tax_id não é um CPF/CNPJ válido.
key_not_found: 422. Validação da chave: nenhum recebedor encontrado para a chave Pix.
account_not_found: 422. Nenhuma conta vinculada ao acesso do token (credencial sem conta ativa).
access_denied: 403. Sem acesso à conta ou sem a permissão da rota.
account_closed: 403. A conta foi encerrada e não pode movimentar.
not_found: 404. Recurso inexistente ou de outra conta.
processing_error: 400. Falha ao processar a solicitação; a message explica.

Status HTTP

200 / 201: sucesso (201 quando algo foi criado). 202: aceito, falta uma etapa (validação da chave).
401: token ausente, inválido ou expirado. Gere outro em /oauth/token.
403, 404, 409, 422: veja o code. Não repita sem corrigir.
429: limite de chamadas; aguarde e tente de novo. 5xx: instabilidade; repita com a mesma chave de idempotência.