# 错误代码 (/zh/docs/pix-processamento/error-codes) 所有错误响应都遵循相同的信封结构。请根据 `errorCode`（稳定）编写你的逻辑，而不是根据 `message`（可能变更）。 | 字段 | 描述 | | ------------------- | ------------------------------------ | | `errorCode` | 稳定代码（例如：`PZD600`）。在你的逻辑中使用它，而不是消息内容。 | | `message` | 可读文本，可能会变更。 | | `statusCode` | 响应的 HTTP 状态。 | | `requestId` | 请求标识符（联系支持时请提供）。 | | `details[]` | 校验错误（400）时，每个错误列出字段 + 原因。 | | `retryAfterSeconds` | 在 429、503 和不可用的 424 中，建议重试请求的秒数。 | ## 按来源分类的 HTTP [#按来源分类的-http] | HTTP | 含义 | 应对措施 | | ----------- | ---------------------------- | ------------------------------------------------------------- | | 400 | 数据无效 | 不要重试；修正请求 | | 401 | 未认证 | 检查 token | | 403 | 无权限 / IP | 不要重试；检查 token 的作用域 / IP | | 404 | 未找到 | 核对 id/clientReference | | 409 | 冲突 | 重试前先查询状态 | | 410 | 已过期 | 资源不再存在 | | 422 | 业务规则 | 按消息内容进行修正 | | 424 | 金融机构失败、拒绝、超时或不可用 | 带退避策略重试；创建操作（存款、Pix 付款、转账）超时时，重新创建前请通过 `clientReference` 查询状态 | | 429 | 速率限制 | 等待 `retryAfterSeconds` | | 500 | PayZu 内部错误 | 再次尝试；若持续存在，联系支持并提供 `requestId` | | 503 | PayZu 暂时不可用 | `retryAfterSeconds` 后重试 | | Timeout（网络） | 在期限内未收到 HTTP 响应，并非 API 返回的状态 | 操作可能已被应用；重新创建前请通过 `clientReference` 查询状态 | > 5xx 始终表示 PayZu 的问题；424 表示金融机构的问题。应用不会发出 502/504：如果你收到这些代码，那来自路径中的代理/CDN，而非 API。 ## 通用错误 [#通用错误] 这些错误可能出现在任何已认证的 `/v1` 路由中，与具体流程无关。 | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | ----------------------- | ---------------------------------------------------------------------------------------------- | | `PZV001` | 400 | 数据无效。请检查所填字段。 | 查看 `details[]`：指出字段和原因。 | | `PZI100` | 500 | 处理请求时发生内部错误。 | 再次尝试；若持续存在，联系支持并提供 `requestId`。 | | `PZF503` | 503 | 服务暂时不可用。请稍后再试。 | PayZu 不可用；带退避策略重试。 | | `PZA100` | 401 | 需要认证或 token 无效。 | 发送有效且激活的 `Authorization: Bearer`。 | | `PZA200` | 403 | 此 token/作用域不允许该操作。 | Token 没有该路由所需的权限，或访问的子域与账户不匹配。 | | `PZA203` | 403 | 不允许从该 IP 地址访问。 | IP 不在白名单内（Pix 付款/转账）。请在配置中放通该 IP。 | | `PZA204` | 403 | 账户已锁定，无法变更。请先解锁账户再进行变更。 | 在账户配置变更时返回，包括创建、编辑、删除和轮换 webhook 密钥。锁定会在资源存在性检查之前评估：账户被锁定时，不存在的 `{id}` 会返回 403 而非 404。请联系支持解锁。 | ## 存款 / Cash-in [#存款--cash-in] 路由：`POST /v1/pix/`、`POST /v1/transactions/`、`GET /v1/pix/`、`GET /v1/pix/qr-code/:transactionId`、`GET /v1/user/deposit-pending/` 和 `/:id` | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | ------------------------- | --------------------------------------------- | | `PZD200` | 422 | 此账户不允许存款。 | 未启用存款；请联系支持。 | | `PZD201` | 422 | 此账户未开通 CNPJ 存款。 | 未启用 CNPJ 付款人。 | | `PZD500` | 424 | 目前没有可用的金融机构。请稍后再试。 | `retryAfterSeconds` 后重试。 | | `PZD600` | 400 | 最小存款金额为 `{min}`。 | 金额低于最小值。 | | `PZD601` | 400 | 最大存款金额为 `{max}`。 | 金额高于最大值。 | | `PZD602` | 400 | 超过 R$ 2.000,00 的存款必须提供证件。 | 请发送 `generatedDocument`。 | | `PZD100` | 424 | 无法在金融机构生成存款。请重试。 | 收款方失败；请再次尝试。 | | `PZD103` | 424 | 达到存款处理超时时间。请重试。 | 处理超时。重新创建前请通过 `clientReference` 查询状态；存款可能已完成。 | ## Pix 付款 / Cash-out [#pix-付款--cash-out] 路由：`POST /v1/withdraw/`、`POST /v1/withdraw/qrcode`、`GET /v1/withdraw/` | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | --------------------------------- | ----------------------------------------------------- | | `PZS200` | 422 | 此账户目前不允许提现。 | 未启用 Pix 付款。 | | `PZS201` | 422 | 仅允许向已注册的收款人进行 CNPJ 提现。 | 请先注册 CNPJ 收款人再付款。 | | `PZS202` | 422 | 超出每日提现限额。 | 请等待次日；限额和已使用额度在 `GET /user` 的 `DailyWithdrawLimit` 中。 | | `PZC200` | 422 | 此操作余额不足。 | 余额不可用；`POST /v1/internal-transfer/` 中也会返回。 | | `PZS102` | 422 | 付款被收款方金融机构拒绝。 | 目的地拒绝；重试前请确认收款人数据。 | | `PZS500` | 424 | 目前没有可用于提现的金融机构。请稍后再试。 | `retryAfterSeconds` 后重试。 | | `PZS600` | 400 | 最小提现金额为 `{min}`。 | 金额低于最小值。 | | `PZS601` | 400 | 最大提现金额为 `{max}`。 | 金额高于最大值。 | | `PZS602` | 400 | 提现金额超出金融机构的限额范围。 | 请调整至收款方限额内。 | | `PZS603` | 400 | 所填金额（`{a}`）与 QR Code 金额（`{b}`）不符。 | 请使用 QR 的精确金额。 | | `PZS604` | 400 | 必须填写金额。 | QR 无固定金额；请填写金额。 | ## 内部转账 [#内部转账] 路由：`POST /v1/internal-transfer/`、`GET /v1/internal-transfer/` Pix 付款章节中列出的 `PZC200`（余额不足）在此也会返回。 | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | -------------------------- | ------------------------------------- | | `PZC201` | 422 | 收款账户不可用。 | 目的账户目前无法收款。 | | `PZC202` | 422 | 转账金额不足以覆盖收款方的 cash-in 手续费。 | 请增加转账金额。 | | `PZC300` | 404 | 收款账户无效或未找到。 | 请核对 `receiverAccountNumber`。 | | `PZC301` | 404 | 未找到内部转账。 | 未在你的账户下找到。 | | `PZC400` | 403 | 付款账户不属于请求者。 | `payerAccountNumber` 必须是 token 本身的账户。 | | `PZC401` | 403 | 此账户未启用内部转账。 | 未启用；请联系支持。 | | `PZC600` | 400 | 不允许转账至自身账户。 | 请填写与付款方不同的目的账户。 | | `PZC602` | 400 | 最小转账金额为 `{min}`。 | 金额低于最小值。 | | `PZC603` | 400 | 最大转账金额为 `{max}`。 | 金额高于最大值。 | ## Pix 密钥 / DICT / QR [#pix-密钥--dict--qr] 路由：`GET /v1/pix/key`、`POST /v1/pix/qrcode/read`、`POST /v1/withdraw/qrcode` | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | ---------------------------------------------- | --------------- | | `PZK101` | 424 | 无法在金融机构查询 QR Code。 | 请再次尝试。 | | `PZK200` | 422 | Pix 密钥无效。 | 密钥无效。 | | `PZK201` | 422 | Pix 密钥与收款人证件不符。 | 密钥与证件不匹配。 | | `PZK300` | 404 | 未找到 Pix 密钥。 | 在 DICT 中未找到该密钥。 | | `PZK301` | 404 | 未找到 QR Code。 | 未找到 QR。 | | `PZK310` | 410 | 此 QR Code 已过期或被收款方金融机构删除。 | 请申请新的 QR。 | | `PZK400` | 403 | 用户未启用 Pix 密钥查询。 | 未启用；请联系支持。 | | `PZK401` | 403 | 用户未启用 QR Code 读取。 | 未启用。 | | `PZK600` | 400 | Pix 密钥无效。格式：CPF、CNPJ、电子邮箱、电话（+55...）或随机（UUID）。 | 请修正格式。 | | `PZK601` | 400 | QR Code 无效或格式错误。 | QR 无法读取。 | ## 查询 / 凭证 / 账户 [#查询--凭证--账户] 路由：`GET /v1/status/`、`GET /v1/user/transactions/` 和 `/:id`、`GET /v1/user/bank-statements/` 和 `/:id`、`POST /v1/user/report/:id/download` | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | ------------------------------------ | ---------------------------------- | | `PZC210` | 409 | 已存在具有此标识符的操作。请检查所填的 clientReference。 | `clientReference` 重复；请使用其他值或查询该操作。 | | `PZC310` | 404 | 未找到交易。 | 未在你的账户下找到。 | | `PZC320` | 422 | 交易尚未处理。 | 交易待处理时凭证不可用。 | | `PZC321` | 422 | 凭证不可用：交易已取消且无凭证。 | 交易已取消，无凭证。 | | `PZI103` | 500 | 缺少完成操作所需的内部数据。 | 请稍后再试；若持续存在，联系支持并提供 `requestId`。 | ## 违规争议（MED） [#违规争议med] 路由：`GET /v1/user/infractions/` 和 `/:id`、`POST /v1/user/infractions/:id/defenses` | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | -------- | ------------------------------------------------------- | | `PZK210` | 409 | 违规争议已关闭。 | 该违规争议不再接受操作；请查询当前状态。 | | `PZK212` | 409 | 抗辩已提交。 | 该违规争议已存在抗辩；请查询 `GET /v1/user/infractions/:id/defenses`。 | ## 重发 callback [#重发-callback] 有三个路由可以重发 callback，各自的错误代码不同。 ### `POST /v1/user/callbacks/resend/webhook/:webhookId` [#post-v1usercallbacksresendwebhookwebhookid] | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | --------------------------- | ------------------------------------ | | `PZW300` | 404 | 未找到 webhook、已停用或不属于该用户 | 请核对 `webhookId` 以及 webhook 是否在账户中激活。 | | `PZW310` | 404 | 未在该 webhook 中找到失败的 callback | 该 webhook 中没有可重发的失败投递。 | ### `POST /v1/user/callbacks/resend` [#post-v1usercallbacksresend] 按筛选条件批量重发。 | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | ------------- | --------------------------- | | `PZG404` | 404 | 未找到符合所提供条件的交易 | 没有交易与所发送的时间窗口和筛选条件匹配；请检查条件。 | ### `POST /v1/user/callbacks/resend/:transactionId` [#post-v1usercallbacksresendtransactionid] 重发单笔交易的 callback。 | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | --------------------- | ---------------------------------------- | | `PZG404` | 404 | 未找到交易或该交易未配置 callback | 请核对 `transactionId` 以及该交易是否配置了 callback。 | 这三个路由在达到重发上限时都会返回 `PZG422`。该代码位于通用代码表中。 ## 金融机构 [#金融机构] 出现在实时查询金融机构的路由中。 | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | ---------------- | ------------------------------------------------------- | | `PZI101` | 500 | 该金融机构不支持此操作。 | 收款方所属机构不支持该操作。请勿重试；请改用其他密钥或其他支付方式。 | | `PZI110` | 424 | 与金融机构通信错误。 | 请再次尝试。 | | `PZI111` | 424 | 金融机构响应超时。请重试。 | 超时；创建操作（存款、Pix 付款、转账）时，重新创建前请通过 `clientReference` 查询状态。 | | `PZF500` | 424 | 金融机构暂时不可用。请稍后再试。 | `retryAfterSeconds` 后重试。 | ## 通用错误 [#通用错误-1] | 代码 | HTTP | 消息 | 应对措施 | | -------- | ---- | --------------- | ------------------------ | | `PZG404` | 404 | 未找到资源。 | 资源不存在。 | | `PZG409` | 409 | 请求与资源当前状态冲突。 | 重试前请查询状态。 | | `PZG410` | 410 | 该资源不再可用。 | 资源已过期或被删除。 | | `PZG422` | 422 | 无法处理该请求。 | 业务规则；请按消息内容修正。 | | `PZG423` | 422 | 金额超过此操作允许的限额。 | 请减少金额或检查你的限额。 | | `PZG429` | 429 | 短时间内请求过多。请稍后再试。 | 请等待 `retryAfterSeconds`。 |