# 错误代码 (/zh/docs/conta-digital/error-codes) 所有拒绝都采用这个格式： ```json { "message": "Saldo insuficiente para este saque.", "code": "WITHDRAW_INSUFFICIENT_BALANCE", "details": { "available": 12500, "required": 20250 } } ``` | 字段 | 说明 | | --------- | --------------------------------------- | | `message` | 葡萄牙语文本，用于展示给使用你系统的人。可能随时变化，所以本页的表格不重复它。 | | `code` | 稳定代码，没有新版本就不会变化。你的系统应根据它决定如何处理。 | | `details` | 拒绝的上下文，存在时才返回。可能不出现。 | ## `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` 之后 [#遇到-502-之后] `PROVIDER_UNAVAILABLE`，或 `details.status` 为 `408` 或 `429` 的 `PROVIDER_REFUSED`，表示银行没有给出最终响应，操作可能已经发生。要重试而不重复执行： * \*\*提现、Pix 复制粘贴码付款和转账：\*\*用同一个 `Idempotency-Key` 重试，或先查询再重新请求。 * \*\*收款：\*\*用同一个 `externalRef` 重试。 * \*\*退款和退回存款：\*\*先查询再重新请求。这些路由不接受 `Idempotency-Key`。 其他 `PROVIDER_REFUSED` 是银行的拒绝：不要重试。 每个路由的拒绝都列在 [API 参考](/docs/conta-digital/endpoints)中。凭证拒绝适用于所有路由。 ## 请求与请求次数限制 [#请求与请求次数限制] | `code` | HTTP | 何时 | | ------------------------------ | ---- | ------------------------------- | | `AUTH_TOO_MANY_REQUESTS` | 429 | 超过了请求次数限制。请等待 `Retry-After`。 | | `RATE_LIMIT_UNAVAILABLE` | 503 | 请求次数限制的控制服务不可用。没有执行任何操作。 | | `REQUEST_INTEGER_OUT_OF_RANGE` | 400 | 请求中的某个数字超出允许范围。 | | `REQUEST_NOT_ALLOWED` | 405 | 该路由不接受这个 HTTP 方法。 | | `REQUEST_NUL_BYTE` | 400 | 请求中含有空字符。 | | `REQUEST_PAYLOAD_TOO_LARGE` | 413 | 请求体超过了允许的大小。 | | `REQUEST_UNKNOWN_QUERY_PARAM` | 400 | 路由不认识其中一个查询参数。 | | `SCHEMA_INVALID` | 400 | 某个字段或参数缺失或值无效。`details` 指出是哪一个。 | | `SCHEMA_MALFORMED_BODY` | 400 | 请求体不是有效的 JSON。 | | `SYSTEM_INTERNAL_ERROR` | 500 | PayZu 内部错误。 | ## 凭证 [#凭证] 适用于所有路由。详见[凭证拒绝](/docs/conta-digital/authentication#凭证拒绝)。 | `code` | HTTP | 何时 | | ------------------------------ | ---- | ------------------------------------------------------ | | `JWT_INVALID_AUTH_FORMAT` | 401 | 缺少 `Authorization` header，或方案既不是 `Bearer` 也不是 `Basic`。 | | `TOKEN_EXPIRED` | 401 | 凭证设有有效期，且已过期。 | | `TOKEN_HOLDER_BLOCKED` | 403 | 账户持有人被冻结。 | | `TOKEN_INVALID` | 401 | 凭证错误、不存在或已吊销，或令牌已过期或被篡改。 | | `TOKEN_INVALID_AUTH_FORMAT` | 401 | `Basic` 无法解码为 `client_id:client_secret`。 | | `TOKEN_IP_NOT_ALLOWED` | 403 | 调用来自凭证 IP 列表之外的 IP。 | | `TOKEN_MISSING_SCOPE` | 403 | 凭证没有该路由的作用域。`details.scope` 指明缺少哪一个。 | | `TOKEN_UNSUPPORTED_GRANT_TYPE` | 400 | 缺少 `grant_type`，或其值不是 `client_credentials`。 | ## 账户与银行 [#账户与银行] | `code` | HTTP | 何时 | | ----------------------------------- | ---- | --------------------------------------------- | | `ACCOUNT_BLOCKED_BY_PROVIDER` | 422 | 银行在账户上冻结了这项操作，直到解除冻结。在转账中，也可能是目标账户的转入被冻结。 | | `ACCOUNT_HELD_BY_STAFF` | 422 | 账户被客服暂扣，直到解除。在转账中，也可能是目标账户被暂扣。 | | `ACCOUNT_NOT_OPERABLE` | 412 | 账户未激活，不能移动资金。 | | `PROVIDER_CAPABILITY_NOT_SUPPORTED` | 422 | 账户不提供这项操作。 | | `PROVIDER_NOT_PROVISIONED` | 412 | 账户尚未完成开立。 | | `PROVIDER_OPERATION_UNAVAILABLE` | 422 | 这项操作目前对该账户不可用。 | | `PROVIDER_REFUSED` | 502 | 银行拒绝了这项操作。见[遇到 `502` 之后](#遇到-502-之后)。 | | `PROVIDER_UNAVAILABLE` | 502 | 银行没有及时响应，操作可能已经发生。见[遇到 `502` 之后](#遇到-502-之后)。 | ## 收款与回调 [#收款与回调] | `code` | HTTP | 何时 | | -------------------------------- | ---- | ----------------------------------------------------------------- | | `CALLBACK_SECRET_ALREADY_ISSUED` | 409 | 账户已有回调密钥。要更换，请使用轮换。 | | `CALLBACK_SECRET_MISSING` | 412 | 操作带有 `callbackUrl`，但账户还没有回调密钥。 | | `PAYMENT_ABOVE_MAXIMUM` | 422 | 金额超过账户的收款最大值（[限额](/docs/conta-digital/statement#限额)中的 `payment`）。 | | `PAYMENT_AMOUNT_NOT_ABOVE_FEE` | 422 | 金额不大于收款手续费。 | | `PAYMENT_BELOW_MINIMUM` | 422 | 金额低于账户的收款最小值。 | | `PAYMENT_CREATION_IN_FLIGHT` | 412 | 带相同 `externalRef` 的收款仍在创建中。几秒后再试。 | | `PAYMENT_DISABLED` | 403 | 该账户的收款已停用。 | | `PAYMENT_EXTERNAL_REF_MISMATCH` | 409 | 已有一笔带此 `externalRef` 的收款，且有数据不同。不一致的字段在 `details.fields` 中。 | | `PAYMENT_INVALID_CURSOR` | 400 | 列表的 `cursor` 无效。从第一页重新开始。 | | `PAYMENT_NOT_FOUND` | 404 | 收款不存在或属于其他账户。 | ## 退款与退回 [#退款与退回] | `code` | HTTP | 何时 | | ----------------------------- | ---- | -------------------------- | | `REFUND_ABOVE_REMAINING` | 422 | 请求的金额超过收款或存款剩余可退的金额。 | | `REFUND_ABOVE_TICKET_MAX` | 422 | 金额超过账户每笔操作的最大值，即提现的最大值。 | | `REFUND_ALREADY_REFUNDED` | 422 | 收款或存款已全额退还。 | | `REFUND_DISABLED` | 403 | 该账户的退款已停用。 | | `REFUND_INFRACTION_OPEN` | 422 | 收款或存款存在进行中的 MED 争议。请等待其结果。 | | `REFUND_INSUFFICIENT_BALANCE` | 422 | 可用余额不足以支付退款。 | | `REFUND_IN_FLIGHT` | 422 | 已有一笔退款正在处理中。请等待其结果。 | | `REFUND_NOT_PAID` | 422 | 收款尚未支付。 | ## 提现与 Pix 复制粘贴码付款 [#提现与-pix-复制粘贴码付款] | `code` | HTTP | 何时 | | ---------------------------------------- | ---- | ------------------------------------------------------------------ | | `QR_AMOUNT_DISAGREES` | 422 | Pix 复制粘贴码上印的金额与银行为其返回的金额不同。请与收款的一方确认金额。 | | `QR_AMOUNT_MISMATCH` | 422 | Pix 复制粘贴码固定了金额，而发送的 `amount` 不同。 | | `QR_AMOUNT_REQUIRED` | 422 | Pix 复制粘贴码没有固定金额，且缺少 `amount`。 | | `QR_CRC` | 400 | Pix 复制粘贴码已损坏。请重新复制。 | | `QR_MALFORMED` | 400 | Pix 复制粘贴码格式无效。 | | `QR_NOT_PIX` | 400 | 发送的文本不是 Pix 复制粘贴码。 | | `WITHDRAW_ABOVE_TICKET_MAX` | 422 | 金额超过账户的提现最大值（[限额](/docs/conta-digital/statement#限额)中的 `withdraw`）。 | | `WITHDRAW_BELOW_TICKET_MIN` | 422 | 金额低于账户的提现最小值。 | | `WITHDRAW_DAILY_LIMIT` | 422 | 该请求将超出 Pix 转出的每日上限（`dailyWithdraw`）。 | | `WITHDRAW_DISABLED` | 403 | 该账户的提现已停用。 | | `WITHDRAW_IDEMPOTENCY_KEY_REUSED` | 409 | 该 `Idempotency-Key` 已用于数据不同的请求。 | | `WITHDRAW_INSUFFICIENT_BALANCE` | 422 | 可用余额不足以支付金额加手续费。`details` 带有 `available` 和 `required`。 | | `WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE` | 422 | 即使 `available` 足够，银行当时也无法支付这笔提现。 | | `WITHDRAW_INVALID_IDEMPOTENCY_KEY` | 400 | `Idempotency-Key` 不是 1 到 255 个可见字符。 | | `WITHDRAW_INVALID_PIX_KEY` | 400 | CPF 或 CNPJ 校验位错误，或 11 位数字既不是 CPF 也不是手机号。 | | `WITHDRAW_NOT_FOUND` | 404 | 提现不存在或属于其他账户。 | | `WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER` | 422 | 银行拒绝了目标密钥。 | | `WITHDRAW_PIX_KEY_TYPE_MISMATCH` | 400 | `pixKeyType` 与密钥不符。`details.inferred` 给出推断出的类型。 | | `WITHDRAW_UNRECOGNIZED_PIX_KEY` | 422 | 无法推断密钥类型。 | ## 收款方查询 [#收款方查询] | `code` | HTTP | 何时 | | ------------------------------------- | ---- | ------------------------------- | | `PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER` | 502 | 银行没有为该账户开放密钥查询。请联系客服：重试无法解决。 | | `PIX_DEST_PIX_KEY` | 404 | 该密钥在 DICT（Pix 的密钥目录）中不存在。请检查密钥。 | | `PIX_DEST_THROTTLED` | 503 | 超过了银行的查询次数限制。稍等片刻后重试。 | | `PIX_DEST_UNAVAILABLE` | 503 | 查询未进行。片刻后重试。 | ## Pix 密钥 [#pix-密钥] | `code` | HTTP | 何时 | | ---------------------------------------- | ---- | --------------------------------------- | | `PIX_KEY_DEFAULT_CANNOT_BE_REMOVED` | 422 | 这是默认密钥。删除前请先把另一个密钥设为默认。 | | `PIX_KEY_DEFAULT_ON_PROVIDER` | 422 | 该密钥是账户的默认密钥，即使列表中还没有显示。删除前请先把另一个密钥设为默认。 | | `PIX_KEY_DOCUMENT_NOT_HOLDER` | 400 | CPF 或 CNPJ 密钥不是账户持有人的证件号。 | | `PIX_KEY_DUPLICATED` | 409 | 该密钥已在本账户中注册。 | | `PIX_KEY_NOT_FOUND` | 404 | 密钥不存在、已删除或属于其他账户。 | | `PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT` | 422 | 密钥不是 `ACTIVE`，不能设为默认。 | | `PIX_KEY_PROVIDER_REFUSED` | 422 | 银行拒绝了该密钥。原因在 `details.reason` 中。 | | `PIX_KEY_RANDOM_KEY_NOT_ALLOWED` | 400 | 请求 `EVP` 密钥时带了 `key`。随机密钥由银行生成。 | | `PIX_KEY_REQUIRED` | 400 | 类型不是 `EVP` 且没有 `key`。 | | `PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER` | 422 | 账户不能创建的密钥类型：`CPF`、`EMAIL` 或 `PHONE`。 | ## 账户间转账 [#账户间转账] | `code` | HTTP | 何时 | | ----------------------------------- | ---- | -------------------------------------------------------------------------- | | `TRANSFER_ABOVE_TICKET_MAX` | 422 | 金额超过账户的转账最大值（[限额](/docs/conta-digital/statement#限额)中的 `internalTransfer`）。 | | `TRANSFER_AMBIGUOUS_DESTINATION` | 422 | 该密钥在多个账户中处于启用状态。 | | `TRANSFER_BELOW_TICKET_MIN` | 422 | 金额低于账户的转账最小值。 | | `TRANSFER_DAILY_LIMIT` | 422 | 该请求将超出转账的每日上限（`dailyInternalTransfer`）。 | | `TRANSFER_DESTINATION` | 404 | 没有任何 PayZu 账户启用了该密钥。 | | `TRANSFER_DESTINATION_NOT_ACTIVE` | 422 | 目标账户未激活。 | | `TRANSFER_DIFFERENT_PROVIDER` | 422 | 目标账户在另一家银行运营。请使用提现。 | | `TRANSFER_DISABLED` | 403 | 该账户的账户间转账已停用。 | | `TRANSFER_IDEMPOTENCY_KEY_REUSED` | 409 | 该 `Idempotency-Key` 已用于其他金额或目的地。 | | `TRANSFER_INSUFFICIENT_BALANCE` | 422 | 可用余额不足以支付金额加手续费。`details` 带有 `available` 和 `required`。 | | `TRANSFER_INVALID_IDEMPOTENCY_KEY` | 400 | `Idempotency-Key` 不是 1 到 255 个可见字符。 | | `TRANSFER_MAIN_ACCOUNT_DESTINATION` | 422 | 该密钥属于 PayZu 的主账户，它不接收转账。要向 PayZu 付款，请使用收款。 | | `TRANSFER_NOT_FOUND` | 404 | 转账不存在或属于其他账户。 | | `TRANSFER_NOT_SUPPORTED` | 422 | 你的账户不能进行账户间转账。 | | `TRANSFER_NO_ORIGIN_KEY` | 422 | 你的账户没有可用于发出转账的启用 Pix 密钥。 | | `TRANSFER_SAME_ACCOUNT` | 422 | 该密钥属于你自己的账户。 | ## 存款与凭证 [#存款与凭证] | `code` | HTTP | 何时 | | ---------------------------- | ---- | --------------------------------------- | | `DEPOSIT_NOT_FOUND` | 404 | 存款不存在或属于其他账户。 | | `RECEIPT_MISSING_END_TO_END` | 422 | 该操作还没有 end-to-end 标识，没有它就无法生成凭证。几分钟后再试。 | | `RECEIPT_NOT_SETTLED` | 422 | 该操作尚未完成。完成后才能生成凭证。 | ## 争议 [#争议] | `code` | HTTP | 何时 | | ---------------------- | ---- | ------------- | | `INFRACTION_NOT_FOUND` | 404 | 争议不存在或属于其他账户。 | ## Webhooks [#webhooks] | `code` | HTTP | 何时 | | ------------------------ | ---- | ------------------------------------------- | | `WEBHOOK_DUPLICATED_URL` | 409 | 账户中的另一个端点已在使用这个 URL。 | | `WEBHOOK_HAS_DELIVERIES` | 409 | 该端点已有投递记录，不能删除。要停止接收，请发送 `isActive: false`。 | | `WEBHOOK_NOT_FOUND` | 404 | 端点不存在或属于其他账户。 |