Ir al contenido
A AmunPay API PixVersión 3.38 · actualizada el Páginas

Errores

Todo error de las rutas /v2/ responde con un cuerpo RFC 7807 (application/problem+json). El POST /oauth/token responde en el formato { "error", "error_description" }; vea Autenticación. title es contrato y no cambia; detail es texto para personas; type es una URL terminada en /erros/ y el title: compare por el title, nunca por el dominio de la URL. violacoes trae, cuando lo hay, el campo y el número que faltó.

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": []
}

Trátelo por el title, no por el status. Un 4xx no cambia si se repite la misma solicitud en el acto. El 429 pasa después del Retry-After; los que dependen del estado, como saldo_insuficiente, limite_excedido, dia_nao_encerrado y reenvio_em_andamento, pasan cuando el estado cambia. Un 5xx o un timeout no significan que la operación falló: consulte el recurso por el id antes de crear otro.

Estado title Cuándo
400 json_invalido El cuerpo no es JSON.
400 requisicao_invalida Campo obligatorio ausente o cuerpo fuera de la forma.
400 campo_desconhecido Campo que la ruta no conoce, donde ella lo rechaza.
400 valor_invalido Dinero fuera del formato "0.00" o fuera del intervalo: cero en un cobro, retiro o devolución, o por encima del máximo.
400 tipo_invalido tipo del retiro diferente de SAQUE o PREMIO.
400 natureza_invalida natureza de la devolución fuera de la lista.
400 txid_invalido txid fuera de 26 a 35 caracteres alfanuméricos.
400 id_envio_invalido idEnvio fuera del formato.
400 id_invalido Id de devolución o de subcuenta fuera del formato.
400 cpf_invalido CPF fuera del formato.
400 cnpj_invalido CNPJ fuera del formato: son 14 posiciones sin puntuación, las 12 primeras dígitos o letras (la minúscula se lee en mayúscula) y las 2 últimas dígitos, con los dígitos verificadores.
400 filtro_invalido Filtro de listado inválido, como cpf y cnpj juntos.
400 documento_invalido El documento del beneficiario no es un CPF o CNPJ válido, o falta; o el cobro trae devedor.cpf y devedor.cnpj juntos.
400 devedor_obrigatorio Cobro sin devedor.cpf ni devedor.cnpj.
400 devedor_pj_nao_permitido Cobro con devedor.cnpj donde capacidades.devedorPJ es false.
400 chave_nao_pertence_ao_documento El dueño de la clave no es el CPF o el CNPJ informado.
400 favorecido_pj_nao_permitido Beneficiario persona jurídica, o clave de persona jurídica con favorecido.cpf, donde capacidades.favorecidoPJ es false.
400 chave_pix_invalida La clave no tiene la forma de ningún tipo, o es un CPF o CNPJ sin los dígitos verificadores.
400 solicitado_em_invalido solicitadoEm fuera del formato o más de 5 minutos en el futuro.
400 validade_invalida validadeSegundos del retiro fuera de 60 a 10800.
400 periodo_invalido de, ate, inicio o fim fuera del formato.
400 periodo_obrigatorio Resumen sin de o sin ate.
400 data_invalida Fecha fuera de AAAA-MM-DD.
400 cursor_invalido Cursor mal formado.
400 limite_invalido limite fuera de 1 a 200.
400 status_invalido Filtro de estado fuera de la lista.
400 url_invalida URL de webhook inválida o sin HTTPS.
400 url_privada URL de webhook en una red privada, o host que no se resuelve en el DNS.
400 familia_desconhecida Desvío de webhook para una familia inexistente.
400 tipos_invalidos tiposHabilitados con un elemento en blanco.
400 janela_invalida Reenvío con fim igual o anterior a inicio, o inicio en el futuro.
400 janela_muito_antiga Reenvío con inicio de hace más de 30 días.
401 acesso_negado Llamada sin Authorization: Bearer.
401 token_invalido Token inválido o expirado. Renuévelo.
401 token_revogado Token revocado antes de expirar. Solicite otro token una vez; si la solicitud es rechazada, hable con soporte.
403 origem_nao_permitida La IP de origen no está entre las IP registradas en la credencial.
403 escopo_insuficiente El token no tiene el alcance de la ruta.
403 merchant_nao_provisionado El client_id no tiene cuenta.
403 conta_bloqueada La cuenta no está ATIVA.
403 conta_em_abertura La cuenta todavía no puede cobrar ni retirar: la institución está definiendo dónde opera. Las lecturas y el webhook funcionan.
403 conta_cnpj_nao_ativo El CNPJ de la cuenta no está ATIVA (activo) en la Receita Federal de Brasil: los cobros y retiros nuevos quedan bloqueados hasta que vuelva a estar activo. Las lecturas y el webhook funcionan.
403 subconta_indisponivel La subcuenta no está ATIVA.
403 subconta_de_outro Credencial de subcuenta solicitando otra subcuenta.
404 nao_encontrado El recurso no existe en esta cuenta.
409 txid_duplicado txid reutilizado con otro deudor, valor, ex.subconta o ex.splitConfig.
409 id_envio_duplicado idEnvio reutilizado con otro valor, tipo, documento del beneficiario, subconta o exigirAprovacao.
409 id_duplicado Id reutilizado con otro cuerpo.
409 reenvio_em_andamento Ya hay un reenvío de webhook en curso.
413 corpo_grande_demais Cuerpo de más de 1 MiB.
422 saldo_insuficiente El disponible no cubre el valor. En el retiro, el valor más la tarifa.
422 saldo_bloqueado_med El disponible no cubre el retiro y la cuenta tiene saldo retenido. GET /v2/ex/bloqueios lista cada retención.
422 limite_excedido Por encima de un tope. Números en violacoes.
422 favorecido_restrito El CPF del beneficiario está restringido.
422 chave_sob_reivindicacao La clave está en portabilidad o reivindicación.
422 chave_exige_documento En esta cuenta el retiro va solo a la clave que es el CPF o el CNPJ válido del beneficiario, y la clave enviada es correo electrónico, teléfono, aleatoria o un documento sin los dígitos verificadores. Vea capacidades.saqueQualquerChave en GET /v2/ex/config.
422 documento_exigido_pela_nominal El retiro vino sin el documento del beneficiario, con el documento opcional en su cuenta, y la cuenta por donde sale exige el documento. Envíe favorecido.cpf o favorecido.cnpj.
422 valor_abaixo_do_minimo El valor del retiro está por debajo del mínimo de retiro de la cuenta, o el del cobro por debajo del mínimo de cobro. El mínimo viene en detail, y no se crea nada.
422 valor_acima_do_maximo El valor del retiro está por encima del máximo por Pix de retiro de la cuenta, o el del cobro por encima del máximo de cobro. El máximo viene en detail, y no se crea nada.
422 pagamento_negado_compliance Rechazo del análisis de riesgo. No repita.
422 cadeia_retry_invalida idEnvioOriginal inválido para repetir el retiro.
422 cobranca_recusada_no_custodiante La institución de la cuenta se negó a emitir el QR. El cobro no se creó; no repita con el mismo cuerpo.
422 nome_do_pagador_obrigatorio En esta cuenta el cobro exige devedor.nome, con el nombre y el apellido donde el CPF de quien pagó llega enmascarado. Vea capacidades.cobrancaSemNome en GET /v2/ex/config.
422 titularidade_sem_confirmacao En esta cuenta no se acepta el cobro con el documento del pagador. Contacte al soporte.
422 pix_nao_creditado Devolución de un Pix que no se acreditó o está retenido.
422 devolucao_unica En esta cuenta cada Pix acepta una única devolución, y este ya tiene una.
422 devolucao_so_integral En esta cuenta la devolución es solo del valor completo del Pix, y el valor solicitado es menor.
422 devolucao_de_outra_conta El Pix entró antes de que el saldo de su cuenta fuera transferido de institución. Su devolución la hacemos nosotros: hable con soporte.
422 devolucao_excede_recebido La suma de las devoluciones superaría lo recibido.
422 devolucao_prazo_excedido Pasaron 90 días desde la liquidación.
422 subconta_nao_encontrada La subcuenta informada no existe.
422 split_config_nao_encontrada ex.splitConfig no existe.
422 dia_nao_encerrado Extracto o saldo de cierre del día en curso.
422 periodo_nao_encerrado Resumen de un período todavía abierto.
422 periodo_longo_demais Resumen de más de 366 días.
422 saque_nao_liquidado Comprobante de un retiro que no está REALIZADO.
422 webhook_nao_configurado Prueba sin webhook activo.
429 limite_requisicoes Por encima del límite de solicitudes. Respete Retry-After.
500 erro_interno Error nuestro.
502 custodiante_indisponivel Falla al emitir el QR en la institución custodia. El cobro no se creó; repita con el mismo txid. Si responde 502 de nuevo sin el encabezado Retry-After, créelo con un txid nuevo. Con Retry-After, repita con el mismo txid después del tiempo indicado, en segundos: 1 cuando la institución tardó y la emisión sigue (el QR que llegue queda guardado, y la repetición recibe el cobro), cuando el mismo cobro está en emisión en otra solicitud, o cuando la institución tiene demasiados cobros en espera o los suyos ya ocupan la mitad de sus lugares; el tiempo que falta de la pausa cuando la institución dejó de emitir el QR de sus cobros y la emisión de ellos está en pausa; y el tiempo que la institución pidió cuando limitó las solicitudes.
503 dict_resolucao_incompleta El directorio no informó la cuenta del beneficiario. Repita.
503 capacidade_indisponivel La cuenta no tiene la capacidad que la ruta exige. GET /v2/ex/config lista las capacidades de la cuenta y el origen de cada una.

Límites de solicitudes #

La API no limita las solicitudes por segundo: no hay tope para cobros, retiros, lecturas ni para el feed de eventos.

Una cuenta que entre en un bucle por un defecto puede recibir un límite de la institución. Solo en ese caso las respuestas traen x-ratelimit-remaining, y un 429 trae Retry-After.