PayZuDocs

错误代码

查看 Markdown
PortuguêsEnglish中文

了解 API 每种拒绝的含义，以及什么时候值得重试。

凭证拒绝API 参考

所有拒绝都采用这个格式：

{
  "message": "Saldo insuficiente para este saque.",
  "code": "WITHDRAW_INSUFFICIENT_BALANCE",
  "details": { "available": 12500, "required": 20250 }
}
字段说明
message葡萄牙语文本，用于展示给使用你系统的人。可能随时变化，所以本页的表格不重复它。
code稳定代码，没有新版本就不会变化。你的系统应根据它决定如何处理。
details拒绝的上下文，存在时才返回。可能不出现。

details 中的内容

  • SCHEMA_INVALID：有问题的字段，按请求体的结构给出。例如 { "customer": { "document": "Informe um CPF ou CNPJ válido." } }。
  • REQUEST_UNKNOWN_QUERY_PARAM：details.unknownParams 列出路由不认识的查询参数，details.accepted 列出它接受的参数。请求体中的未知字段会被忽略。
  • 429：details.retryAfterSeconds，与 Retry-After header 中的秒数相同。
  • PROVIDER_UNAVAILABLE 和 PROVIDER_REFUSED：银行返回的状态和原因，在 details.status 和 details.reason 中。银行没有响应时，details.status 为 null。

何时重试

状态怎么做
400、404、409不修正请求就不要重试：同样的调用会收到同样的拒绝。
403、422不要原样重试。有些会随账户状态变化：RECEIPT_MISSING_END_TO_END（几分钟后再试）、REFUND_IN_FLIGHT（等待上一笔退款的结果）、*_INSUFFICIENT_BALANCE（余额到账后）、*_DAILY_LIMIT（第二天，按巴西利亚时间）和 TOKEN_HOLDER_BLOCKED（冻结解除后）。
401不要循环重试。获取新令牌或修正凭证。
412只在完成缺失的步骤之后重试，该步骤由 code 指明。PAYMENT_CREATION_IN_FLIGHT 片刻后即可解决。
429等待 Retry-After 中的时间后重试。
502操作可能已经发生。见下文。
503等待后重试。没有执行任何操作。
500、504、超时以递增的间隔重试。如果操作涉及资金变动，遵循 502 的规则。

遇到 502 之后

PROVIDER_UNAVAILABLE，或 details.status 为 408 或 429 的 PROVIDER_REFUSED，表示银行没有给出最终响应，操作可能已经发生。要重试而不重复执行：

  • **提现、Pix 复制粘贴码付款和转账：**用同一个 Idempotency-Key 重试，或先查询再重新请求。
  • **收款：**用同一个 externalRef 重试。
  • **退款和退回存款：**先查询再重新请求。这些路由不接受 Idempotency-Key。

其他 PROVIDER_REFUSED 是银行的拒绝：不要重试。

每个路由的拒绝都列在 API 参考中。凭证拒绝适用于所有路由。

请求与请求次数限制

codeHTTP何时
AUTH_TOO_MANY_REQUESTS429超过了请求次数限制。请等待 Retry-After。
RATE_LIMIT_UNAVAILABLE503请求次数限制的控制服务不可用。没有执行任何操作。
REQUEST_INTEGER_OUT_OF_RANGE400请求中的某个数字超出允许范围。
REQUEST_NOT_ALLOWED405该路由不接受这个 HTTP 方法。
REQUEST_NUL_BYTE400请求中含有空字符。
REQUEST_PAYLOAD_TOO_LARGE413请求体超过了允许的大小。
REQUEST_UNKNOWN_QUERY_PARAM400路由不认识其中一个查询参数。
SCHEMA_INVALID400某个字段或参数缺失或值无效。details 指出是哪一个。
SCHEMA_MALFORMED_BODY400请求体不是有效的 JSON。
SYSTEM_INTERNAL_ERROR500PayZu 内部错误。

凭证

适用于所有路由。详见凭证拒绝。

codeHTTP何时
JWT_INVALID_AUTH_FORMAT401缺少 Authorization header，或方案既不是 Bearer 也不是 Basic。
TOKEN_EXPIRED401凭证设有有效期，且已过期。
TOKEN_HOLDER_BLOCKED403账户持有人被冻结。
TOKEN_INVALID401凭证错误、不存在或已吊销，或令牌已过期或被篡改。
TOKEN_INVALID_AUTH_FORMAT401Basic 无法解码为 client_id:client_secret。
TOKEN_IP_NOT_ALLOWED403调用来自凭证 IP 列表之外的 IP。
TOKEN_MISSING_SCOPE403凭证没有该路由的作用域。details.scope 指明缺少哪一个。
TOKEN_UNSUPPORTED_GRANT_TYPE400缺少 grant_type，或其值不是 client_credentials。

账户与银行

codeHTTP何时
ACCOUNT_BLOCKED_BY_PROVIDER422银行在账户上冻结了这项操作，直到解除冻结。在转账中，也可能是目标账户的转入被冻结。
ACCOUNT_HELD_BY_STAFF422账户被客服暂扣，直到解除。在转账中，也可能是目标账户被暂扣。
ACCOUNT_NOT_OPERABLE412账户未激活，不能移动资金。
PROVIDER_CAPABILITY_NOT_SUPPORTED422账户不提供这项操作。
PROVIDER_NOT_PROVISIONED412账户尚未完成开立。
PROVIDER_OPERATION_UNAVAILABLE422这项操作目前对该账户不可用。
PROVIDER_REFUSED502银行拒绝了这项操作。见遇到 502 之后。
PROVIDER_UNAVAILABLE502银行没有及时响应，操作可能已经发生。见遇到 502 之后。

收款与回调

codeHTTP何时
CALLBACK_SECRET_ALREADY_ISSUED409账户已有回调密钥。要更换，请使用轮换。
CALLBACK_SECRET_MISSING412操作带有 callbackUrl，但账户还没有回调密钥。
PAYMENT_ABOVE_MAXIMUM422金额超过账户的收款最大值（限额中的 payment）。
PAYMENT_AMOUNT_NOT_ABOVE_FEE422金额不大于收款手续费。
PAYMENT_BELOW_MINIMUM422金额低于账户的收款最小值。
PAYMENT_CREATION_IN_FLIGHT412带相同 externalRef 的收款仍在创建中。几秒后再试。
PAYMENT_DISABLED403该账户的收款已停用。
PAYMENT_EXTERNAL_REF_MISMATCH409已有一笔带此 externalRef 的收款，且有数据不同。不一致的字段在 details.fields 中。
PAYMENT_INVALID_CURSOR400列表的 cursor 无效。从第一页重新开始。
PAYMENT_NOT_FOUND404收款不存在或属于其他账户。

退款与退回

codeHTTP何时
REFUND_ABOVE_REMAINING422请求的金额超过收款或存款剩余可退的金额。
REFUND_ABOVE_TICKET_MAX422金额超过账户每笔操作的最大值，即提现的最大值。
REFUND_ALREADY_REFUNDED422收款或存款已全额退还。
REFUND_DISABLED403该账户的退款已停用。
REFUND_INFRACTION_OPEN422收款或存款存在进行中的 MED 争议。请等待其结果。
REFUND_INSUFFICIENT_BALANCE422可用余额不足以支付退款。
REFUND_IN_FLIGHT422已有一笔退款正在处理中。请等待其结果。
REFUND_NOT_PAID422收款尚未支付。

提现与 Pix 复制粘贴码付款

codeHTTP何时
QR_AMOUNT_DISAGREES422Pix 复制粘贴码上印的金额与银行为其返回的金额不同。请与收款的一方确认金额。
QR_AMOUNT_MISMATCH422Pix 复制粘贴码固定了金额，而发送的 amount 不同。
QR_AMOUNT_REQUIRED422Pix 复制粘贴码没有固定金额，且缺少 amount。
QR_CRC400Pix 复制粘贴码已损坏。请重新复制。
QR_MALFORMED400Pix 复制粘贴码格式无效。
QR_NOT_PIX400发送的文本不是 Pix 复制粘贴码。
WITHDRAW_ABOVE_TICKET_MAX422金额超过账户的提现最大值（限额中的 withdraw）。
WITHDRAW_BELOW_TICKET_MIN422金额低于账户的提现最小值。
WITHDRAW_DAILY_LIMIT422该请求将超出 Pix 转出的每日上限（dailyWithdraw）。
WITHDRAW_DISABLED403该账户的提现已停用。
WITHDRAW_IDEMPOTENCY_KEY_REUSED409该 Idempotency-Key 已用于数据不同的请求。
WITHDRAW_INSUFFICIENT_BALANCE422可用余额不足以支付金额加手续费。details 带有 available 和 required。
WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE422即使 available 足够，银行当时也无法支付这笔提现。
WITHDRAW_INVALID_IDEMPOTENCY_KEY400Idempotency-Key 不是 1 到 255 个可见字符。
WITHDRAW_INVALID_PIX_KEY400CPF 或 CNPJ 校验位错误，或 11 位数字既不是 CPF 也不是手机号。
WITHDRAW_NOT_FOUND404提现不存在或属于其他账户。
WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER422银行拒绝了目标密钥。
WITHDRAW_PIX_KEY_TYPE_MISMATCH400pixKeyType 与密钥不符。details.inferred 给出推断出的类型。
WITHDRAW_UNRECOGNIZED_PIX_KEY422无法推断密钥类型。

收款方查询

codeHTTP何时
PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER502银行没有为该账户开放密钥查询。请联系客服：重试无法解决。
PIX_DEST_PIX_KEY404该密钥在 DICT（Pix 的密钥目录）中不存在。请检查密钥。
PIX_DEST_THROTTLED503超过了银行的查询次数限制。稍等片刻后重试。
PIX_DEST_UNAVAILABLE503查询未进行。片刻后重试。

Pix 密钥

codeHTTP何时
PIX_KEY_DEFAULT_CANNOT_BE_REMOVED422这是默认密钥。删除前请先把另一个密钥设为默认。
PIX_KEY_DEFAULT_ON_PROVIDER422该密钥是账户的默认密钥，即使列表中还没有显示。删除前请先把另一个密钥设为默认。
PIX_KEY_DOCUMENT_NOT_HOLDER400CPF 或 CNPJ 密钥不是账户持有人的证件号。
PIX_KEY_DUPLICATED409该密钥已在本账户中注册。
PIX_KEY_NOT_FOUND404密钥不存在、已删除或属于其他账户。
PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT422密钥不是 ACTIVE，不能设为默认。
PIX_KEY_PROVIDER_REFUSED422银行拒绝了该密钥。原因在 details.reason 中。
PIX_KEY_RANDOM_KEY_NOT_ALLOWED400请求 EVP 密钥时带了 key。随机密钥由银行生成。
PIX_KEY_REQUIRED400类型不是 EVP 且没有 key。
PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER422账户不能创建的密钥类型：CPF、EMAIL 或 PHONE。

账户间转账

codeHTTP何时
TRANSFER_ABOVE_TICKET_MAX422金额超过账户的转账最大值（限额中的 internalTransfer）。
TRANSFER_AMBIGUOUS_DESTINATION422该密钥在多个账户中处于启用状态。
TRANSFER_BELOW_TICKET_MIN422金额低于账户的转账最小值。
TRANSFER_DAILY_LIMIT422该请求将超出转账的每日上限（dailyInternalTransfer）。
TRANSFER_DESTINATION404没有任何 PayZu 账户启用了该密钥。
TRANSFER_DESTINATION_NOT_ACTIVE422目标账户未激活。
TRANSFER_DIFFERENT_PROVIDER422目标账户在另一家银行运营。请使用提现。
TRANSFER_DISABLED403该账户的账户间转账已停用。
TRANSFER_IDEMPOTENCY_KEY_REUSED409该 Idempotency-Key 已用于其他金额或目的地。
TRANSFER_INSUFFICIENT_BALANCE422可用余额不足以支付金额加手续费。details 带有 available 和 required。
TRANSFER_INVALID_IDEMPOTENCY_KEY400Idempotency-Key 不是 1 到 255 个可见字符。
TRANSFER_MAIN_ACCOUNT_DESTINATION422该密钥属于 PayZu 的主账户，它不接收转账。要向 PayZu 付款，请使用收款。
TRANSFER_NOT_FOUND404转账不存在或属于其他账户。
TRANSFER_NOT_SUPPORTED422你的账户不能进行账户间转账。
TRANSFER_NO_ORIGIN_KEY422你的账户没有可用于发出转账的启用 Pix 密钥。
TRANSFER_SAME_ACCOUNT422该密钥属于你自己的账户。

存款与凭证

codeHTTP何时
DEPOSIT_NOT_FOUND404存款不存在或属于其他账户。
RECEIPT_MISSING_END_TO_END422该操作还没有 end-to-end 标识，没有它就无法生成凭证。几分钟后再试。
RECEIPT_NOT_SETTLED422该操作尚未完成。完成后才能生成凭证。

争议

codeHTTP何时
INFRACTION_NOT_FOUND404争议不存在或属于其他账户。

Webhooks

codeHTTP何时
WEBHOOK_DUPLICATED_URL409账户中的另一个端点已在使用这个 URL。
WEBHOOK_HAS_DELIVERIES409该端点已有投递记录，不能删除。要停止接收，请发送 isActive: false。
WEBHOOK_NOT_FOUND404端点不存在或属于其他账户。
安全Postman

本页内容

details 中的内容何时重试遇到 502 之后请求与请求次数限制凭证账户与银行收款与回调退款与退回提现与 Pix 复制粘贴码付款收款方查询Pix 密钥账户间转账存款与凭证争议Webhooks