Ir para o conteúdo
P Prontopag API PixPáginas

Erros

Todo erro responde um corpo RFC 7807. title é contrato e não muda; detail é texto para gente; type é uma URL sob o domínio da API terminada em /erros/ e o title. violacoes traz, quando há, o campo e o número que faltou.

PUT /v2/ex/pix/SAQ03J1ZK7M9QW3ERT5TY6UI8O
{
  "tipo": "SAQUE",
  "valor": "10000.00",
  "solicitadoEm": "2026-09-18T12:00:00Z",
  "favorecido": { "chave": "fulano@exemplo.com", "cpf": "12345678909" }
}
→ 422
{
  "type": ".../erros/saldo_insuficiente",
  "title": "saldo_insuficiente",
  "status": 422,
  "detail": "saldo disponível insuficiente",
  "correlationId": "01M2SX29RA7F19V4Q76VFTSAHS",
  "violacoes": []
}

Trate pelo title, não pelo status. 4xx repetido com o mesmo corpo dá o mesmo resultado. 5xx e timeout não significam que a operação falhou: consulte o recurso pelo id antes de criar outro.

Status title Quando
400 json_invalido O corpo não é JSON.
400 requisicao_invalida Campo obrigatório ausente ou corpo fora da forma.
400 campo_desconhecido Campo que a rota não conhece, onde ela recusa isso.
400 valor_invalido Dinheiro fora do formato "0.00".
400 txid_invalido txid fora de 26 a 35 caracteres alfanuméricos.
400 id_envio_invalido idEnvio fora do formato.
400 id_invalido Id de devolução ou de sub-conta fora do formato.
400 cpf_invalido CPF fora do formato.
400 cnpj_invalido CNPJ fora do formato.
400 devedor_obrigatorio Cobrança sem devedor.cpf.
400 devedor_pj_nao_permitido Cobrança com devedor.cnpj.
400 chave_nao_pertence_ao_documento O dono da chave não é o CPF informado.
400 favorecido_pj_nao_permitido A chave é de pessoa jurídica.
400 solicitado_em_invalido solicitadoEm fora do formato ou da janela.
400 periodo_invalido de, ate, inicio ou fim fora do formato.
400 data_invalida Data fora de AAAA-MM-DD.
400 cursor_invalido Cursor malformado.
400 limite_invalido limite não é inteiro positivo.
400 status_invalido Filtro de status fora da lista.
400 url_invalida URL de webhook inválida ou sem HTTPS.
400 url_privada URL de webhook em rede privada.
400 familia_desconhecida Desvio de webhook para família inexistente.
401 acesso_negado Chamada sem Authorization: Bearer.
401 token_revogado Credencial revogada, ou segredo rotacionado por vazamento.
403 origem_nao_permitida O IP de origem está fora da allowlist da credencial.
403 escopo_insuficiente O token não tem o escopo da rota.
403 merchant_nao_provisionado O client_id não tem conta.
403 conta_bloqueada A conta não está ATIVA.
403 subconta_indisponivel A sub-conta não está ATIVA.
403 subconta_de_outro Credencial de sub-conta pedindo outra sub-conta.
404 nao_encontrado O recurso não existe nesta conta.
409 txid_duplicado txid reutilizado com outro corpo.
409 id_envio_duplicado idEnvio reutilizado com outro corpo.
409 id_duplicado Id reutilizado com outro corpo.
409 reenvio_em_andamento Já há reenvio de webhook em curso.
413 corpo_grande_demais Corpo acima de 1 MiB.
422 saldo_insuficiente O disponível não cobre o valor.
422 saldo_bloqueado_med Há saldo, retido por contestação.
422 limite_excedido Acima de um teto. Números em violacoes.
422 favorecido_restrito O CPF do favorecido está restrito.
422 chave_sob_reivindicacao A chave está em portabilidade ou reivindicação.
422 pagamento_negado_compliance Recusa da análise de risco. Não repita.
422 cadeia_retry_invalida idEnvioOriginal inválido para repetir o saque.
422 cob_nao_pagavel A cobrança não está ATIVA.
422 pix_nao_creditado Devolução de um Pix que não creditou.
422 devolucao_excede_recebido A soma das devoluções passaria do recebido.
422 devolucao_prazo_excedido Passaram 90 dias da liquidação.
422 devolucao_terminal A devolução já teve desfecho.
422 payout_terminal O saque já teve desfecho.
422 subconta_nao_encontrada ex.subconta não existe.
422 split_config_nao_encontrada ex.splitConfig não existe.
422 dia_nao_encerrado Extrato ou saldo de fechamento do dia corrente.
422 periodo_nao_encerrado Resumo de período ainda aberto.
422 periodo_longo_demais Resumo acima de 366 dias.
422 saque_nao_liquidado Comprovante de saque não liquidado.
422 webhook_nao_configurado Teste ou reenvio sem webhook.
429 limite_requisicoes Acima do limite de requisições. Respeite Retry-After.
500 erro_interno Erro nosso.
502 custodiante_indisponivel Falha ao emitir o QR na instituição custodiante. A cobrança não foi criada; repita com o mesmo txid.
503 dict_resolucao_incompleta O diretório não respondeu a conta do favorecido. Repita.
503 capacidade_indisponivel A conta não tem a capacidade que a rota exige. GET /v2/ex/config lista as capacidades da conta e a origem de cada uma.

Limites de requisições #

Rotas Por segundo Pico
Escrita (cobranças) 400 800
Saques 100 200
Leituras 800 1600
Feed de eventos 10 20

Toda resposta traz x-ratelimit-remaining. Um 429 traz Retry-After.