Ir para o conteúdo
A AmunPay API PixVersão 3.38 · atualizada em Páginas

Erros

Todo erro das rotas /v2/ responde um corpo RFC 7807 (application/problem+json). O POST /oauth/token responde no formato { "error", "error_description" }; veja Autenticação. title é contrato e não muda; detail é texto para gente; type é uma URL terminada em /erros/ e o title: compare pelo title, nunca pelo domínio da URL. 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": "12345678909", "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. Um 4xx não muda repetindo o mesmo pedido na hora. O 429 passa depois do Retry-After; os que dependem de estado, como saldo_insuficiente, limite_excedido, dia_nao_encerrado e reenvio_em_andamento, passam quando o estado muda. 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" ou fora do intervalo: zero numa cobrança, saque ou devolução, ou acima do máximo.
400 tipo_invalido tipo do saque diferente de SAQUE ou PREMIO.
400 natureza_invalida natureza da devolução fora da lista.
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: são 14 posições sem pontuação, as 12 primeiras dígitos ou letras (a minúscula é lida em maiúscula) e as 2 últimas dígitos, com os dígitos verificadores.
400 filtro_invalido Filtro de listagem inválido, como cpf e cnpj juntos.
400 documento_invalido O documento do favorecido não é um CPF ou CNPJ válido, ou falta; ou a cobrança traz devedor.cpf e devedor.cnpj juntos.
400 devedor_obrigatorio Cobrança sem devedor.cpf nem devedor.cnpj.
400 devedor_pj_nao_permitido Cobrança com devedor.cnpj onde capacidades.devedorPJ é false.
400 chave_nao_pertence_ao_documento O dono da chave não é o CPF ou o CNPJ informado.
400 favorecido_pj_nao_permitido Favorecido pessoa jurídica, ou chave de pessoa jurídica com favorecido.cpf, onde capacidades.favorecidoPJ é false.
400 chave_pix_invalida A chave não tem a forma de nenhum tipo, ou é um CPF ou CNPJ sem os dígitos verificadores.
400 solicitado_em_invalido solicitadoEm fora do formato ou mais de 5 minutos no futuro.
400 validade_invalida validadeSegundos do saque fora de 60 a 10800.
400 periodo_invalido de, ate, inicio ou fim fora do formato.
400 periodo_obrigatorio Resumo sem de ou sem ate.
400 data_invalida Data fora de AAAA-MM-DD.
400 cursor_invalido Cursor malformado.
400 limite_invalido limite fora de 1 a 200.
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, ou host que não resolve no DNS.
400 familia_desconhecida Desvio de webhook para família inexistente.
400 tipos_invalidos tiposHabilitados com um item em branco.
400 janela_invalida Reenvio com fim igual ou antes de inicio, ou inicio no futuro.
400 janela_muito_antiga Reenvio com inicio há mais de 30 dias.
401 acesso_negado Chamada sem Authorization: Bearer.
401 token_invalido Token inválido ou expirado. Renove.
401 token_revogado Token revogado antes de expirar. Peça outro token uma vez; se o pedido for recusado, fale com o suporte.
403 origem_nao_permitida O IP de origem não está entre os IPs cadastrados na 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 conta_em_abertura A conta ainda não pode cobrar nem sacar: a instituição está definindo onde ela opera. Leituras e webhook funcionam.
403 conta_cnpj_nao_ativo O CNPJ da conta não está ATIVA na Receita Federal: cobrança e saque novos ficam parados até ele voltar a ATIVA. Leituras e webhook funcionam.
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 devedor, valor, ex.subconta ou ex.splitConfig.
409 id_envio_duplicado idEnvio reutilizado com outro valor, tipo, documento do favorecido, subconta ou exigirAprovacao.
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. No saque, o valor mais a tarifa.
422 saldo_bloqueado_med O disponível não cobre o saque e a conta tem saldo retido. GET /v2/ex/bloqueios lista cada retençã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 chave_exige_documento Nesta conta o saque vai só para a chave que é o CPF ou o CNPJ válido do favorecido, e a chave mandada é e-mail, telefone, aleatória ou um documento sem os dígitos verificadores. Veja capacidades.saqueQualquerChave em GET /v2/ex/config.
422 documento_exigido_pela_nominal O saque veio sem o documento do favorecido, com o documento opcional na sua conta, e a conta por onde ele sai exige o documento. Mande favorecido.cpf ou favorecido.cnpj.
422 valor_abaixo_do_minimo O valor do saque está abaixo do mínimo de saque da conta, ou o da cobrança abaixo do mínimo de cobrança. O mínimo vem em detail, e nada é criado.
422 valor_acima_do_maximo O valor do saque está acima do máximo por Pix de saque da conta, ou o da cobrança acima do máximo de cobrança. O máximo vem em detail, e nada é criado.
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 cobranca_recusada_no_custodiante A instituição da conta recusou emitir o QR. A cobrança não foi criada; não repita com o mesmo corpo.
422 nome_do_pagador_obrigatorio Nesta conta a cobrança exige devedor.nome, com o nome e o sobrenome onde o CPF de quem pagou chega mascarado. Veja capacidades.cobrancaSemNome em GET /v2/ex/config.
422 titularidade_sem_confirmacao Nesta conta a cobrança com o documento do pagador não é aceita. Fale com o suporte.
422 pix_nao_creditado Devolução de um Pix que não creditou ou está retido.
422 devolucao_unica Nesta conta cada Pix aceita uma única devolução, e este já tem uma.
422 devolucao_so_integral Nesta conta a devolução é só do valor inteiro do Pix, e o valor pedido é menor.
422 devolucao_de_outra_conta O Pix entrou antes de o saldo da sua conta ser transferido de instituição. A devolução dele é feita por nós: fale com o suporte.
422 devolucao_excede_recebido A soma das devoluções passaria do recebido.
422 devolucao_prazo_excedido Passaram 90 dias da liquidação.
422 subconta_nao_encontrada A sub-conta informada 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 que não está REALIZADO.
422 webhook_nao_configurado Teste sem webhook ativo.
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. Se responder 502 de novo sem o cabeçalho Retry-After, crie com um txid novo. Com o Retry-After, repita com o mesmo txid depois do tempo indicado, em segundos: 1 quando a instituição demorou e a emissão segue (o QR que chegar fica gravado, e a repetição recebe a cobrança), quando a mesma cobrança está em emissão noutra requisição, ou quando a instituição tem cobranças demais em espera ou as suas já ocupam metade dos lugares dela; o tempo que falta da pausa quando a instituição parou de emitir o QR das suas cobranças e a emissão delas está pausada; e o tempo que a instituição pediu quando ela limitou as requisições.
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 #

A API não limita requisições por segundo: não há teto para cobranças, saques, leituras nem para o feed de eventos.

Uma conta que entrar em laço por defeito pode receber um limite da instituição. Só nesse caso as respostas trazem x-ratelimit-remaining, e um 429 traz Retry-After.