Referência
Erros e códigos
Toda resposta de erro tem um código estável em inglês e uma mensagem em português. Trate os erros pelo código.
Formato
{
"code": "validation_failed",
"message": "Alguns campos precisam de atenção.",
"fields": {
"payer.document": "invalid_document"
}
}code: código estável. Use no seu código para decidir o que fazer.message: frase em português para mostrar ou registrar. Pode mudar de texto.fields: só emvalidation_failed. Diz qual campo está errado e por quê.support_code: só em erros inesperados. Envie ao suporte.
Status HTTP
| HTTP | O que significa | Pode repetir? |
|---|---|---|
| 400 | Requisição malformada ou cabeçalho faltando. | Não. Corrija antes. |
| 401 | Chave ausente, errada ou revogada. | Não. Confira a chave. |
| 403 | A chave não tem o escopo, ou a origem foi recusada. | Não. |
| 404 | O recurso não existe na sua conta. | Não. |
| 409 | Conflito: external_id repetido ou chave de idempotência em andamento. | Só idempotency_in_progress, com a mesma chave. |
| 413 | Corpo grande demais. | Não. |
| 422 | Campos inválidos ou chave de idempotência reutilizada. | Não. Corrija antes. |
| 429 | Limite de requisições atingido. | Sim, depois de esperar. |
| 5xx | Falha temporária do nosso lado. | Sim, com a mesma Idempotency-Key. |
Como repetir
Repita só 429, 5xx e falhas de rede. Espere mais a cada tentativa (por exemplo 1, 2, 4, 8 segundos) e pare depois de algumas tentativas. Em POST, repita sempre com a mesma Idempotency-Key.
Erros de campo
| Código | Mensagem |
|---|---|
required | Campo obrigatório. |
invalid | Valor inválido. |
invalid_document | Informe um CPF ou CNPJ válido. |
amount_out_of_range | Valor fora dos limites permitidos. |
Todos os códigos
| Código | Mensagem |
|---|---|
invalid_request | Requisição inválida. |
invalid_period | Período inválido. Escolha datas até hoje, com no máximo 24 meses. |
unknown_field | A requisição contém campos não permitidos. |
unsupported_media_type | Formato da requisição não suportado. |
body_too_large | A requisição é grande demais. |
validation_failed | Alguns campos precisam de atenção. |
unauthenticated | Faça login para continuar. |
too_many_attempts | Muitas tentativas. Aguarde alguns minutos e tente novamente. |
origin_forbidden | Origem da requisição não permitida. |
forbidden | Você não tem permissão para esta ação. |
not_found | Não encontrado. |
insufficient_scope | Esta chave de API não tem permissão para esta operação. |
payments_unavailable | Pagamentos Pix estão temporariamente indisponíveis. Tente novamente em alguns minutos. |
duplicate_external_id | Já existe um pagamento com este external_id. |
invalid_transition | Esta ação não é permitida no status atual. |
insufficient_balance | Saldo disponível insuficiente para esta operação. |
payment_not_refundable | Este pagamento não pode ser reembolsado: ele não foi pago ou já foi reembolsado por completo. |
payout_key_required | Cadastre uma chave Pix de saque antes de solicitar um saque. |
payout_key_pending | Já existe uma troca de chave Pix aguardando análise. |
payout_key_conflict | Outra alteração da chave Pix de saque foi feita ao mesmo tempo. Consulte suas chaves e tente de novo. |
infraction_open | Este pagamento tem uma contestação em aberto. O reembolso só pode seguir depois que ela for resolvida. |
daily_limit_exceeded | O limite diário de saques foi atingido. Tente novamente amanhã. |
reauth_failed | Senha incorreta. Confira e tente de novo. |
reauth_required | Por segurança, confirme sua senha para continuar. |
delivery_not_dead | Só é possível reenviar entregas que falharam em todas as tentativas. |
idempotency_key_required | Cabeçalho Idempotency-Key obrigatório. |
idempotency_key_reused | Esta Idempotency-Key já foi usada com outro conteúdo. |
idempotency_in_progress | Uma requisição com esta Idempotency-Key ainda está em andamento. |
method_not_allowed | Método não permitido. |
internal_error | Erro interno. Tente novamente em instantes. |
step_up_required | Confirme o código do autenticador para continuar. |
stale_version | Outra pessoa alterou estes dados agora mesmo. Recarregue a página e tente de novo. |
webhook_token_unavailable | O endereço completo deste webhook não pode ser exibido. Gere um novo token para obter um endereço. |