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ó em validation_failed. Diz qual campo está errado e por quê.
  • support_code: só em erros inesperados. Envie ao suporte.

Status HTTP

HTTPO que significaPode repetir?
400Requisição malformada ou cabeçalho faltando.Não. Corrija antes.
401Chave ausente, errada ou revogada.Não. Confira a chave.
403A chave não tem o escopo, ou a origem foi recusada.Não.
404O recurso não existe na sua conta.Não.
409Conflito: external_id repetido ou chave de idempotência em andamento.Só idempotency_in_progress, com a mesma chave.
413Corpo grande demais.Não.
422Campos inválidos ou chave de idempotência reutilizada.Não. Corrija antes.
429Limite de requisições atingido.Sim, depois de esperar.
5xxFalha 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ódigoMensagem
requiredCampo obrigatório.
invalidValor inválido.
invalid_documentInforme um CPF ou CNPJ válido.
amount_out_of_rangeValor fora dos limites permitidos.

Todos os códigos

CódigoMensagem
invalid_requestRequisição inválida.
invalid_periodPeríodo inválido. Escolha datas até hoje, com no máximo 24 meses.
unknown_fieldA requisição contém campos não permitidos.
unsupported_media_typeFormato da requisição não suportado.
body_too_largeA requisição é grande demais.
validation_failedAlguns campos precisam de atenção.
unauthenticatedFaça login para continuar.
too_many_attemptsMuitas tentativas. Aguarde alguns minutos e tente novamente.
origin_forbiddenOrigem da requisição não permitida.
forbiddenVocê não tem permissão para esta ação.
not_foundNão encontrado.
insufficient_scopeEsta chave de API não tem permissão para esta operação.
payments_unavailablePagamentos Pix estão temporariamente indisponíveis. Tente novamente em alguns minutos.
duplicate_external_idJá existe um pagamento com este external_id.
invalid_transitionEsta ação não é permitida no status atual.
insufficient_balanceSaldo disponível insuficiente para esta operação.
payment_not_refundableEste pagamento não pode ser reembolsado: ele não foi pago ou já foi reembolsado por completo.
payout_key_requiredCadastre uma chave Pix de saque antes de solicitar um saque.
payout_key_pendingJá existe uma troca de chave Pix aguardando análise.
payout_key_conflictOutra alteração da chave Pix de saque foi feita ao mesmo tempo. Consulte suas chaves e tente de novo.
infraction_openEste pagamento tem uma contestação em aberto. O reembolso só pode seguir depois que ela for resolvida.
daily_limit_exceededO limite diário de saques foi atingido. Tente novamente amanhã.
reauth_failedSenha incorreta. Confira e tente de novo.
reauth_requiredPor segurança, confirme sua senha para continuar.
delivery_not_deadSó é possível reenviar entregas que falharam em todas as tentativas.
idempotency_key_requiredCabeçalho Idempotency-Key obrigatório.
idempotency_key_reusedEsta Idempotency-Key já foi usada com outro conteúdo.
idempotency_in_progressUma requisição com esta Idempotency-Key ainda está em andamento.
method_not_allowedMétodo não permitido.
internal_errorErro interno. Tente novamente em instantes.
step_up_requiredConfirme o código do autenticador para continuar.
stale_versionOutra pessoa alterou estes dados agora mesmo. Recarregue a página e tente de novo.
webhook_token_unavailableO endereço completo deste webhook não pode ser exibido. Gere um novo token para obter um endereço.
fee_changedA tarifa de saque mudou. Confira o novo valor líquido e confirme de novo.
withdrawals_unavailableSaques estão indisponíveis no momento. Tente novamente mais tarde.
withdrawals_not_allowedSua conta está em análise. Os saques serão liberados após a aprovação.