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." }
}
}campossó aparece emdados_invalidos: diz qual campo está errado.- Nos dados do cliente, as chaves de
campossaem comoname,email,cpfephone. - Trate pelo
codigo, nunca pelo texto damensagem.
Códigos
| HTTP | Código | O que fazer |
|---|---|---|
| 400 | json_invalido | Corpo não é um JSON válido (ou, no saque, falta o valor inteiro). |
| 400 | idempotency_key_invalida | A Idempotency-Key está fora do formato. |
| 400 | idempotency_key_obrigatoria | Saque sem Idempotency-Key. |
| 401 | nao_autorizado | Chave errada ou revogada. |
| 401 | chave_expirada | Chave passou da validade: crie outra. |
| 403 | https_obrigatorio | Use https e troque a chave. |
| 403 | conta_nao_aprovada | Espere a aprovação da conta. |
| 403 | ip_nao_autorizado | Cadastre o IP do servidor no painel. |
| 403 | ip_obrigatorio | Saque exige pelo menos um IP autorizado. |
| 403 | sem_permissao | A chave não tem a permissão daquele endereço. |
| 403 | recurso_indisponivel_em_teste | Chave de teste (gp_test_) chamando saldo ou saque. |
| 403 | somente_chave_de_teste | Chave de produção (gp_live_) no endereço de teste (/sandbox). |
| 403 | chave_de_teste_na_producao | Chave de teste (gp_test_) no endereço de produção. |
| 429 | limite_cobrancas_teste | Mais de 200 cobranças de teste guardadas na conta. Elas saem sozinhas depois de 7 dias. |
| 404 | nao_encontrado | Cobrança ou saque não existe (ou é de outra conta). |
| 404 | rota_inexistente | Endereço errado. |
| 409 | em_andamento | O mesmo pedido ainda está sendo feito: tente de novo em instantes. |
| 422 | dados_invalidos | Algum campo errado: veja campos. |
| 422 | idempotency_key_reusada | A mesma Idempotency-Key com outro corpo: use outra chave. |
| 422 | valor_indisponivel | Este valor não está disponível agora para a sua conta. Tente outro valor ou fale com o suporte. |
| 422 | limite_vendedor_novo | Conta nova chegou ao limite de Pix do mês (a mensagem traz os detalhes). |
| 422 | recusado_antifraude | O antifraude recusou este Pix (ex.: comprador bloqueado ou muitos Pix seguidos do mesmo comprador). |
| 422 | 2fa_obrigatorio | Saque sem o 2FA ligado na conta do vendedor: ligue em Configurações › Segurança. |
| 422 | saque_recusado | Regra de saque (saldo, mínimo, saques pausados…): a mensagem diz o motivo. |
| 422 | sem_conta_bancaria, conta_bancaria_inexistente, conta_bancaria_em_analise, conta_bancaria_recusada, conta_bancaria_alterada | Problema na conta bancária do saque: confira em Financeiro. |
| 429 | muitas_requisicoes | Passou do limite da chave ou de cobranças em 10 minutos. Espere e tente de novo. |
| 429 | limite_vendedor | Passou do limite da conta (todas as chaves juntas). |
| 429 | limite_pendentes | Pix pendentes demais em aberto: espere alguns vencerem ou serem pagos. |
| 429 | banco_no_limite | Muitos Pix na plataforma agora: tente em instantes. |
| 429 | muitas_chaves_invalidas | Muitas chaves erradas da mesma rede: espere 1 minuto. |
| 500 | erro_interno | Falha nossa: tente de novo com a mesma Idempotency-Key. |
| 503 | pix_indisponivel | Nenhum 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.