Comece por aqui

Erros

Todo erro volta com um status HTTP e um JSON com o codigo (fixo, para o seu sistema tratar) e a mensagem (texto em português, pode mudar).

Formato

{
  "erro": {
    "codigo": "dados_invalidos",
    "mensagem": "CPF inválido.",
    "campos": { "cpf": "CPF inválido." }
  }
}
  • campos só aparece em dados_invalidos: diz qual campo está errado.
  • Nos dados do cliente, as chaves de campos saem como name, email, cpf e phone.
  • Trate pelo codigo, nunca pelo texto da mensagem.

Códigos

HTTPCódigoO que fazer
400json_invalidoCorpo não é um JSON válido (ou, no saque, falta o valor inteiro).
400idempotency_key_invalidaA Idempotency-Key está fora do formato.
400idempotency_key_obrigatoriaSaque sem Idempotency-Key.
401nao_autorizadoChave errada ou revogada.
401chave_expiradaChave passou da validade: crie outra.
403https_obrigatorioUse https e troque a chave.
403conta_nao_aprovadaEspere a aprovação da conta.
403ip_nao_autorizadoCadastre o IP do servidor no painel.
403ip_obrigatorioSaque exige pelo menos um IP autorizado.
403sem_permissaoA chave não tem a permissão daquele endereço.
403recurso_indisponivel_em_testeChave de teste (gp_test_) chamando saldo ou saque.
403somente_chave_de_testeChave de produção (gp_live_) no endereço de teste (/sandbox).
403chave_de_teste_na_producaoChave de teste (gp_test_) no endereço de produção.
429limite_cobrancas_testeMais de 200 cobranças de teste guardadas na conta. Elas saem sozinhas depois de 7 dias.
404nao_encontradoCobrança ou saque não existe (ou é de outra conta).
404rota_inexistenteEndereço errado.
409em_andamentoO mesmo pedido ainda está sendo feito: tente de novo em instantes.
422dados_invalidosAlgum campo errado: veja campos.
422idempotency_key_reusadaA mesma Idempotency-Key com outro corpo: use outra chave.
422valor_indisponivelEste valor não está disponível agora para a sua conta. Tente outro valor ou fale com o suporte.
422limite_vendedor_novoConta nova chegou ao limite de Pix do mês (a mensagem traz os detalhes).
422recusado_antifraudeO antifraude recusou este Pix (ex.: comprador bloqueado ou muitos Pix seguidos do mesmo comprador).
4222fa_obrigatorioSaque sem o 2FA ligado na conta do vendedor: ligue em Configurações › Segurança.
422saque_recusadoRegra de saque (saldo, mínimo, saques pausados…): a mensagem diz o motivo.
422sem_conta_bancaria, conta_bancaria_inexistente, conta_bancaria_em_analise, conta_bancaria_recusada, conta_bancaria_alteradaProblema na conta bancária do saque: confira em Financeiro.
429muitas_requisicoesPassou do limite da chave ou de cobranças em 10 minutos. Espere e tente de novo.
429limite_vendedorPassou do limite da conta (todas as chaves juntas).
429limite_pendentesPix pendentes demais em aberto: espere alguns vencerem ou serem pagos.
429banco_no_limiteMuitos Pix na plataforma agora: tente em instantes.
429muitas_chaves_invalidasMuitas chaves erradas da mesma rede: espere 1 minuto.
500erro_internoFalha nossa: tente de novo com a mesma Idempotency-Key.
503pix_indisponivelNenhum banco Pix disponível agora: tente de novo com a mesma Idempotency-Key.

Trabalhamos com mais de um banco: se um cair, a cobrança é gerada em outro sem você perceber. O 503 só aparece se todos estiverem fora.