跳到正文
A AmunPay API Pix版本 3.38 · 更新于 页面

错误

所有 /v2/ 路由的错误都返回 RFC 7807 正文（application/problem+json）。POST /oauth/token 以 { "error", "error_description" } 格式响应；见认证。title 是契约，不会改变；detail 是给人看的文字；type 是以 /erros/ 加 title 结尾的 URL：请按 title 比较，切勿依据 URL 的域名。适用时，violacoes 会返回未满足条件的字段和对应的数值。

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

请按 title 处理，而不是按 status。4xx 不会因为立即重复同一请求而改变。429 在 Retry-After 之后可以通过；依赖状态的错误，例如 saldo_insuficiente、limite_excedido、dia_nao_encerrado 和 reenvio_em_andamento，在状态改变后可以通过。5xx 和超时并不表示操作失败：在新建之前，请先按 id 查询该资源。

状态码 title 触发条件
400 json_invalido 正文不是 JSON。
400 requisicao_invalida 缺少必填字段，或正文结构不对。
400 campo_desconhecido 路由不认识的字段，仅限拒绝未知字段的路由。
400 valor_invalido 金额不符合 "0.00" 格式或超出范围：收款、提现或退款为零，或超过最大值。
400 tipo_invalido 提现的 tipo 不是 SAQUE 或 PREMIO。
400 natureza_invalida 退款的 natureza 不在列表中。
400 txid_invalido txid 不是 26 至 35 位字母数字字符。
400 id_envio_invalido idEnvio 格式错误。
400 id_invalido 退款或子账户的 id 格式错误。
400 cpf_invalido CPF 格式错误。
400 cnpj_invalido CNPJ 格式错误：应为 14 位，不含标点，前 12 位为数字或字母（小写按大写读取），后 2 位为数字，并带有校验位。
400 filtro_invalido 列表的过滤条件无效，例如同时使用 cpf 和 cnpj。
400 documento_invalido 收款人的证件号不是有效的 CPF 或 CNPJ，或缺失；或收款同时带有 devedor.cpf 和 devedor.cnpj。
400 devedor_obrigatorio 收款既没有 devedor.cpf 也没有 devedor.cnpj。
400 devedor_pj_nao_permitido 在 capacidades.devedorPJ 为 false 时收款带有 devedor.cnpj。
400 chave_nao_pertence_ao_documento 密钥的所有者不是所填的 CPF 或 CNPJ。
400 favorecido_pj_nao_permitido 在 capacidades.favorecidoPJ 为 false 时，收款人是企业，或企业密钥搭配 favorecido.cpf。
400 chave_pix_invalida 密钥不符合任何类型的格式，或是校验位无效的 CPF 或 CNPJ。
400 solicitado_em_invalido solicitadoEm 格式错误，或比当前时间晚 5 分钟以上。
400 validade_invalida 提现的 validadeSegundos 不在 60 至 10800 之间。
400 periodo_invalido de、ate、inicio 或 fim 格式错误。
400 periodo_obrigatorio 汇总缺少 de 或 ate。
400 data_invalida 日期不符合 AAAA-MM-DD。
400 cursor_invalido 游标格式错误。
400 limite_invalido limite 不在 1 至 200 之间。
400 status_invalido 状态过滤值不在列表中。
400 url_invalida webhook URL 无效或不是 HTTPS。
400 url_privada webhook URL 位于私有网络，或主机名无法通过 DNS 解析。
400 familia_desconhecida webhook 分流指向不存在的族。
400 tipos_invalidos tiposHabilitados 中有空白项。
400 janela_invalida 重新发送的 fim 等于或早于 inicio，或 inicio 是将来的时间。
400 janela_muito_antiga 重新发送的 inicio 早于 30 天前。
401 acesso_negado 调用未带 Authorization: Bearer。
401 token_invalido 令牌无效或已过期。请重新获取。
401 token_revogado 令牌在过期前被吊销。请重新申请一次令牌；如果申请被拒绝，请联系技术支持。
403 origem_nao_permitida 来源 IP 不在凭证登记的 IP 中。
403 escopo_insuficiente 令牌没有该路由所需的权限范围。
403 merchant_nao_provisionado 该 client_id 没有账户。
403 conta_bloqueada 账户状态不是 ATIVA。
403 conta_em_abertura 账户暂时无法收款或提现：机构正在确定其运营所在的账户。查询和 webhook 正常可用。
403 conta_cnpj_nao_ativo 账户的 CNPJ 在巴西联邦税务局的状态不是 ATIVA（有效）：在其恢复有效之前，新的收款和提现都会被阻止。查询和 webhook 正常可用。
403 subconta_indisponivel 子账户状态不是 ATIVA。
403 subconta_de_outro 子账户的凭证请求了另一个子账户。
404 nao_encontrado 该资源在此账户中不存在。
409 txid_duplicado txid 被重复使用，但债务人、金额、ex.subconta 或 ex.splitConfig 不同。
409 id_envio_duplicado idEnvio 被重复使用，但金额、tipo、收款人证件号、subconta 或 exigirAprovacao 不同。
409 id_duplicado id 被重复使用，但正文不同。
409 reenvio_em_andamento 已有一次 webhook 重新发送正在进行。
413 corpo_grande_demais 正文超过 1 MiB。
422 saldo_insuficiente 可用余额不足以支付该金额。提现时为金额加手续费。
422 saldo_bloqueado_med 可用余额不足以支付提现，且账户有冻结余额。GET /v2/ex/bloqueios 列出每一项冻结。
422 limite_excedido 超过某项上限。数值在 violacoes 中。
422 favorecido_restrito 收款人的 CPF 受到限制。
422 chave_sob_reivindicacao 该密钥正在进行可携转或所有权申领。
422 chave_exige_documento 此账户的提现只能发往即为收款人有效 CPF 或 CNPJ 的密钥，而发送的密钥是电子邮件、电话、随机密钥或校验位无效的证件号。见 GET /v2/ex/config 中的 capacidades.saqueQualquerChave。
422 documento_exigido_pela_nominal 提现未带收款人证件，您的账户证件为可选，而提现经由的账户要求证件。请发送 favorecido.cpf 或 favorecido.cnpj。
422 valor_abaixo_do_minimo 提现金额低于该账户的最低提现金额，或收款金额低于最低收款金额。最低金额在 detail 中返回，不会创建任何内容。
422 valor_acima_do_maximo 提现金额高于该账户每笔提现 Pix 的最高金额，或收款金额高于最高收款金额。最高金额在 detail 中返回，不会创建任何内容。
422 pagamento_negado_compliance 被风险分析拒绝。请勿重试。
422 cadeia_retry_invalida idEnvioOriginal 不能用于重试该提现。
422 cobranca_recusada_no_custodiante 账户所在机构拒绝签发 QR 码。收款未创建；不要用相同的正文重试。
422 nome_do_pagador_obrigatorio 此账户的收款要求 devedor.nome；在付款人 CPF 被遮蔽的账户中，须包含名和姓。见 GET /v2/ex/config 中的 capacidades.cobrancaSemNome。
422 titularidade_sem_confirmacao 此账户不接受带付款人证件的收款。请联系支持。
422 pix_nao_creditado 对没有入账或已被冻结的 Pix 申请退款。
422 devolucao_unica 此账户中每笔 Pix 只接受一次退款，而这笔已经有一次了。
422 devolucao_so_integral 此账户中只能退还 Pix 的全额，而请求的 valor 更小。
422 devolucao_de_outra_conta 该 Pix 在您的账户余额转移机构之前到账。其退款由我们处理：请联系技术支持。
422 devolucao_excede_recebido 退款累计金额将超过收到的金额。
422 devolucao_prazo_excedido 已超过结算后 90 天。
422 subconta_nao_encontrada 指定的子账户不存在。
422 split_config_nao_encontrada ex.splitConfig 不存在。
422 dia_nao_encerrado 请求了当天的对账单或日终余额。
422 periodo_nao_encerrado 汇总的期间尚未结束。
422 periodo_longo_demais 汇总超过 366 天。
422 saque_nao_liquidado 请求了状态不是 REALIZADO 的提现的回单。
422 webhook_nao_configurado 没有启用的 webhook 时进行测试。
429 limite_requisicoes 超过请求频率限制。请遵守 Retry-After。
500 erro_interno 我们这边的错误。
502 custodiante_indisponivel 在托管机构签发 QR 码失败。收款未创建；请使用同一个 txid 重试。如果再次返回 502 且没有 Retry-After 头，请用新的 txid 创建。带有 Retry-After 时，请在指示的秒数后使用同一个 txid 重试：当机构响应慢而签发仍在继续时（之后到达的 QR 码会被保存，重试会收到该收款）、当同一笔收款正在另一个请求中签发时、或当机构等待中的收款过多或您的收款已占用其一半名额时，为 1；当机构停止为您的收款签发 QR 码、签发处于暂停状态时，为暂停剩余的时间；当机构限制了请求时，为机构要求的时间。
503 dict_resolucao_incompleta 目录服务没有返回收款人的账户。请重试。
503 capacidade_indisponivel 该账户不具备该路由所需的功能。GET /v2/ex/config 列出账户的各项功能及其来源。

请求频率限制 #

API 不限制每秒请求数：收款、提现、读取和事件流都没有上限。

因缺陷而陷入循环的账户可能会被机构设置限制。只有在这种情况下，响应才会带有 x-ratelimit-remaining，429 会带有 Retry-After。