PayZuDocs

错误代码

查看 Markdown
PortuguêsEnglish中文

API 可能返回的所有错误，包含可供你编程使用的稳定代码、每个代码的含义以及你的系统应如何响应。

错误处理认证术语表（HTTP 代码）

所有错误响应都遵循相同的信封结构。请根据 errorCode（稳定）编写你的逻辑，而不是根据 message（可能变更）。

字段描述
errorCode稳定代码（例如：PZD600）。在你的逻辑中使用它，而不是消息内容。
message可读文本，可能会变更。
statusCode响应的 HTTP 状态。
requestId请求标识符（联系支持时请提供）。
details[]校验错误（400）时，每个错误列出字段 + 原因。
retryAfterSeconds在 429、503 和不可用的 424 中，建议重试请求的秒数。

按来源分类的 HTTP

HTTP含义应对措施
400数据无效不要重试；修正请求
401未认证检查 token
403无权限 / IP不要重试；检查 token 的作用域 / IP
404未找到核对 id/clientReference
409冲突重试前先查询状态
410已过期资源不再存在
422业务规则按消息内容进行修正
424金融机构失败、拒绝、超时或不可用带退避策略重试；创建操作（存款、Pix 付款、转账）超时时，重新创建前请通过 clientReference 查询状态
429速率限制等待 retryAfterSeconds
500PayZu 内部错误再次尝试；若持续存在，联系支持并提供 requestId
503PayZu 暂时不可用retryAfterSeconds 后重试
Timeout（网络）在期限内未收到 HTTP 响应，并非 API 返回的状态操作可能已被应用；重新创建前请通过 clientReference 查询状态

5xx 始终表示 PayZu 的问题；424 表示金融机构的问题。应用不会发出 502/504：如果你收到这些代码，那来自路径中的代理/CDN，而非 API。

通用错误

这些错误可能出现在任何已认证的 /v1 路由中，与具体流程无关。

代码HTTP消息应对措施
PZV001400数据无效。请检查所填字段。查看 details[]：指出字段和原因。
PZI100500处理请求时发生内部错误。再次尝试；若持续存在，联系支持并提供 requestId。
PZF503503服务暂时不可用。请稍后再试。PayZu 不可用；带退避策略重试。
PZA100401需要认证或 token 无效。发送有效且激活的 Authorization: Bearer。
PZA200403此 token/作用域不允许该操作。Token 没有该路由所需的权限，或访问的子域与账户不匹配。
PZA203403不允许从该 IP 地址访问。IP 不在白名单内（Pix 付款/转账）。请在配置中放通该 IP。
PZA204403账户已锁定，无法变更。请先解锁账户再进行变更。在账户配置变更时返回，包括创建、编辑、删除和轮换 webhook 密钥。锁定会在资源存在性检查之前评估：账户被锁定时，不存在的 {id} 会返回 403 而非 404。请联系支持解锁。

存款 / Cash-in

路由：POST /v1/pix/、POST /v1/transactions/、GET /v1/pix/、GET /v1/pix/qr-code/:transactionId、GET /v1/user/deposit-pending/ 和 /:id

代码HTTP消息应对措施
PZD200422此账户不允许存款。未启用存款；请联系支持。
PZD201422此账户未开通 CNPJ 存款。未启用 CNPJ 付款人。
PZD500424目前没有可用的金融机构。请稍后再试。retryAfterSeconds 后重试。
PZD600400最小存款金额为 {min}。金额低于最小值。
PZD601400最大存款金额为 {max}。金额高于最大值。
PZD602400超过 R$ 2.000,00 的存款必须提供证件。请发送 generatedDocument。
PZD100424无法在金融机构生成存款。请重试。收款方失败；请再次尝试。
PZD103424达到存款处理超时时间。请重试。处理超时。重新创建前请通过 clientReference 查询状态；存款可能已完成。

Pix 付款 / Cash-out

路由：POST /v1/withdraw/、POST /v1/withdraw/qrcode、GET /v1/withdraw/

代码HTTP消息应对措施
PZS200422此账户目前不允许提现。未启用 Pix 付款。
PZS201422仅允许向已注册的收款人进行 CNPJ 提现。请先注册 CNPJ 收款人再付款。
PZS202422超出每日提现限额。请等待次日；限额和已使用额度在 GET /user 的 DailyWithdrawLimit 中。
PZC200422此操作余额不足。余额不可用；POST /v1/internal-transfer/ 中也会返回。
PZS102422付款被收款方金融机构拒绝。目的地拒绝；重试前请确认收款人数据。
PZS500424目前没有可用于提现的金融机构。请稍后再试。retryAfterSeconds 后重试。
PZS600400最小提现金额为 {min}。金额低于最小值。
PZS601400最大提现金额为 {max}。金额高于最大值。
PZS602400提现金额超出金融机构的限额范围。请调整至收款方限额内。
PZS603400所填金额（{a}）与 QR Code 金额（{b}）不符。请使用 QR 的精确金额。
PZS604400必须填写金额。QR 无固定金额；请填写金额。

内部转账

路由：POST /v1/internal-transfer/、GET /v1/internal-transfer/

Pix 付款章节中列出的 PZC200（余额不足）在此也会返回。

代码HTTP消息应对措施
PZC201422收款账户不可用。目的账户目前无法收款。
PZC202422转账金额不足以覆盖收款方的 cash-in 手续费。请增加转账金额。
PZC300404收款账户无效或未找到。请核对 receiverAccountNumber。
PZC301404未找到内部转账。未在你的账户下找到。
PZC400403付款账户不属于请求者。payerAccountNumber 必须是 token 本身的账户。
PZC401403此账户未启用内部转账。未启用；请联系支持。
PZC600400不允许转账至自身账户。请填写与付款方不同的目的账户。
PZC602400最小转账金额为 {min}。金额低于最小值。
PZC603400最大转账金额为 {max}。金额高于最大值。

Pix 密钥 / DICT / QR

路由：GET /v1/pix/key、POST /v1/pix/qrcode/read、POST /v1/withdraw/qrcode

代码HTTP消息应对措施
PZK101424无法在金融机构查询 QR Code。请再次尝试。
PZK200422Pix 密钥无效。密钥无效。
PZK201422Pix 密钥与收款人证件不符。密钥与证件不匹配。
PZK300404未找到 Pix 密钥。在 DICT 中未找到该密钥。
PZK301404未找到 QR Code。未找到 QR。
PZK310410此 QR Code 已过期或被收款方金融机构删除。请申请新的 QR。
PZK400403用户未启用 Pix 密钥查询。未启用；请联系支持。
PZK401403用户未启用 QR Code 读取。未启用。
PZK600400Pix 密钥无效。格式：CPF、CNPJ、电子邮箱、电话（+55...）或随机（UUID）。请修正格式。
PZK601400QR Code 无效或格式错误。QR 无法读取。

查询 / 凭证 / 账户

路由：GET /v1/status/、GET /v1/user/transactions/ 和 /:id、GET /v1/user/bank-statements/ 和 /:id、POST /v1/user/report/:id/download

代码HTTP消息应对措施
PZC210409已存在具有此标识符的操作。请检查所填的 clientReference。clientReference 重复；请使用其他值或查询该操作。
PZC310404未找到交易。未在你的账户下找到。
PZC320422交易尚未处理。交易待处理时凭证不可用。
PZC321422凭证不可用：交易已取消且无凭证。交易已取消，无凭证。
PZI103500缺少完成操作所需的内部数据。请稍后再试；若持续存在，联系支持并提供 requestId。

违规争议（MED）

路由：GET /v1/user/infractions/ 和 /:id、POST /v1/user/infractions/:id/defenses

代码HTTP消息应对措施
PZK210409违规争议已关闭。该违规争议不再接受操作；请查询当前状态。
PZK212409抗辩已提交。该违规争议已存在抗辩；请查询 GET /v1/user/infractions/:id/defenses。

重发 callback

有三个路由可以重发 callback，各自的错误代码不同。

POST /v1/user/callbacks/resend/webhook/:webhookId

代码HTTP消息应对措施
PZW300404未找到 webhook、已停用或不属于该用户请核对 webhookId 以及 webhook 是否在账户中激活。
PZW310404未在该 webhook 中找到失败的 callback该 webhook 中没有可重发的失败投递。

POST /v1/user/callbacks/resend

按筛选条件批量重发。

代码HTTP消息应对措施
PZG404404未找到符合所提供条件的交易没有交易与所发送的时间窗口和筛选条件匹配；请检查条件。

POST /v1/user/callbacks/resend/:transactionId

重发单笔交易的 callback。

代码HTTP消息应对措施
PZG404404未找到交易或该交易未配置 callback请核对 transactionId 以及该交易是否配置了 callback。

这三个路由在达到重发上限时都会返回 PZG422。该代码位于通用代码表中。

金融机构

出现在实时查询金融机构的路由中。

代码HTTP消息应对措施
PZI101500该金融机构不支持此操作。收款方所属机构不支持该操作。请勿重试；请改用其他密钥或其他支付方式。
PZI110424与金融机构通信错误。请再次尝试。
PZI111424金融机构响应超时。请重试。超时；创建操作（存款、Pix 付款、转账）时，重新创建前请通过 clientReference 查询状态。
PZF500424金融机构暂时不可用。请稍后再试。retryAfterSeconds 后重试。

通用错误

代码HTTP消息应对措施
PZG404404未找到资源。资源不存在。
PZG409409请求与资源当前状态冲突。重试前请查询状态。
PZG410410该资源不再可用。资源已过期或被删除。
PZG422422无法处理该请求。业务规则；请按消息内容修正。
PZG423422金额超过此操作允许的限额。请减少金额或检查你的限额。
PZG429429短时间内请求过多。请稍后再试。请等待 retryAfterSeconds。
Pix 密钥类型术语表

本页内容

按来源分类的 HTTP通用错误存款 / Cash-inPix 付款 / Cash-out内部转账Pix 密钥 / DICT / QR查询 / 凭证 / 账户违规争议（MED）重发 callbackPOST /v1/user/callbacks/resend/webhook/:webhookIdPOST /v1/user/callbacks/resendPOST /v1/user/callbacks/resend/:transactionId金融机构通用错误