Pix ProcessamentoPix Processamento Docs

错误代码

PortuguêsEnglish中文
错误处理身份认证术语表（HTTP 状态码）

每个错误响应都遵循同一个信封格式。请用 errorCode（稳定）而非 message（可能会变）来编写你的逻辑。

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

按来源划分的 HTTP

HTTP含义处理方式
400数据无效不要重试；修正请求
401未认证检查 token
403无权限 / IP不要重试；检查 token 的作用域 / IP
404未找到核对 id/clientReference
409冲突重试前先查询状态
410已过期资源不再存在
422业务规则根据消息修正
429Rate limit等待 retryAfterSeconds
502 / 504金融机构故障/超时创建类操作（收款、提现、转账）请先通过 clientReference 查询状态再决定是否重建；仅幂等/查询类操作可带退避自动重试
503当前不可用在 retryAfterSeconds 后重试
500服务器内部错误重试；若持续，携带 requestId 联系支持团队

通用

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

代码HTTP消息处理方式
PZV001400Dados inválidos. Verifique os campos informados.查看 details[]：指明字段和原因。
PZI100500Erro interno ao processar a solicitação.重试；若持续，携带 requestId 联系支持团队。
PZA100401Autenticação necessária ou token inválido.发送有效且有效期内的 Authorization: Bearer。
PZA200403Operação não permitida para este token/escopo.Token 不具备该路由所需的权限，或访问的子域与账户不匹配。
PZA203403Acesso não permitido a partir deste endereço de IP.IP 不在白名单内（提现/转账）。在配置中放行该 IP。
PZA204403Conta bloqueada para alterações. Desbloqueie a conta antes de alterar.当账户被锁定禁止变更时，由 PATCH /v1/user 及其他配置变更返回。联系支持团队解锁。

收款 / Cash-in

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

代码HTTP消息处理方式
PZD200422Depósito não permitido para esta conta.收款未开通；联系支持团队。
PZD201422Depósitos de CNPJ não estão liberados para esta conta.CNPJ 付款方未开通。
PZD500503Nenhuma instituição financeira disponível no momento. Tente novamente em instantes.在 retryAfterSeconds 后重试。
PZD600400O valor mínimo do depósito é {min}.金额低于最小值。
PZD601400O valor máximo do depósito é {max}.金额高于最大值。
PZD602400Para depósitos acima de {limite} é obrigatório informar o documento.发送 generatedDocument。
PZD100502Não foi possível gerar o depósito junto à instituição financeira. Tente novamente.收款方故障；重试。
PZD103504O tempo limite de processamento do depósito foi atingido. Tente novamente.处理超时。重新创建前请先通过 clientReference 查询状态，收款可能已完成。

提现 / Cash-out

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

代码HTTP消息处理方式
PZS200422Saque não permitido para esta conta no momento.提现未开通。
PZS201422Saque para CNPJ permitido apenas para favorecidos cadastrados.提现到 CNPJ 前请先登记收款人。
PZS202422Limite diário de saque excedido.等待次日或申请调整限额。
PZC200422Saldo insuficiente para esta operação.余额不足；POST /v1/internal-transfer/ 也会返回此代码。
PZS102422Pagamento rejeitado pela instituição financeira do recebedor.被目标机构拒绝；重试前请核对收款人信息。
PZS500503Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes.在 retryAfterSeconds 后重试。
PZS600400O valor mínimo do saque é {min}.金额低于最小值。
PZS601400O valor máximo do saque é {max}.金额高于最大值。
PZS602400O valor do saque está fora dos limites da instituição financeira.调整到收款方的限额内。
PZS603400O valor informado ({a}) não corresponde ao valor do QR Code ({b}).使用 QR 中的确切金额。
PZS604400É obrigatório informar o valor.QR 无固定金额；请提供金额。

内部转账

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

提现部分列出的 PZC200（余额不足）也会在此返回。

代码HTTP消息处理方式
PZC201422Conta destinatária indisponível.目标账户当前无法收款。
PZC202422O valor da transferência não cobre a taxa de cash-in do recebedor.提高转账金额。
PZC300404Conta destinatária inválida ou não encontrada.核对 receiverAccountNumber。
PZC301404Transferência interna não encontrada.在你的账户下未找到。
PZC400403A conta pagadora não pertence ao solicitante.payerAccountNumber 必须是 token 所属的账户。
PZC401403Transferência interna não habilitada para esta conta.未开通；联系支持团队。
PZC600400Não é permitido transferir para a própria conta.目标账户必须与付款账户不同。
PZC602400O valor mínimo da transferência é {min}.金额低于最小值。
PZC603400O valor máximo da transferência é {max}.金额高于最大值。

Pix 密钥 / DICT / QR

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

代码HTTP消息处理方式
PZK101502Não foi possível consultar o QR Code junto à instituição financeira.重试。
PZK200422Chave Pix inválida.密钥无效。
PZK201422A chave Pix não corresponde ao documento do destinatário.密钥与文件不匹配。
PZK300404Chave Pix não encontrada.在 DICT 中未找到密钥。
PZK301404QR Code não encontrado.未找到 QR。
PZK310410Este QR Code expirou ou foi removido pela instituição financeira recebedora.请求新的 QR。
PZK400403Consulta de chave Pix não habilitada para o usuário.未开通；联系支持团队。
PZK401403Leitura de QR Code não habilitada para o usuário.未开通。
PZK600400Chave Pix inválida. Formatos: CPF, CNPJ, e-mail, telefone (+55...) ou aleatória (UUID).修正格式。
PZK601400QR Code inválido ou mal formatado.QR 无法读取。

查询 / 凭证 / 账户

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

代码HTTP消息处理方式
PZC210409Já existe uma operação com este identificador. Verifique o clientReference informado.clientReference 重复；改用其他值或查询该操作。
PZC310404Transação não encontrada.在你的账户下未找到。
PZC320422Transação ainda não processada.处于待处理状态时凭证不可用。
PZC321422Comprovante indisponível: transação cancelada sem documento.交易已取消且无凭证。
PZI103500Dado interno ausente para concluir a operação.稍后重试；若持续，携带 requestId 联系支持团队。

违规（MED）

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

代码HTTP消息处理方式
PZK210409Infração já encerrada.该违规不再接受操作；查询当前状态。
PZK211422Infração não está em análise manual.仅当违规处于人工审核时才可执行该操作。
PZK212409Defesa já enviada.该违规已有申辩；通过 GET /v1/user/infractions/:id/defenses 查询。

金融机构

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

代码HTTP消息处理方式
PZI101500Operação não suportada para esta instituição financeira.收款方不支持该操作。
PZI110502Erro de comunicação com a instituição financeira.重试。
PZI111504A instituição financeira demorou para responder. Tente novamente.超时；重试。
PZF500503Instituição financeira temporariamente indisponível. Tente novamente em instantes.在 retryAfterSeconds 后重试。

通用错误

代码HTTP消息处理方式
PZG404404Recurso não encontrado.资源不存在。
PZG409409A solicitação conflita com o estado atual do recurso.重试前先查询状态。
PZG410410Este recurso não está mais disponível.资源已过期或已删除。
PZG422422Não foi possível processar a solicitação.业务规则；根据消息修正。
PZG423422O valor excede o limite permitido para esta operação.降低金额或检查你的限额。
PZG429429Muitas requisições em curto período. Tente novamente em instantes.等待 retryAfterSeconds。

Pix 密钥类型

Tipos de chave Pix aceitos pela API Pix Processamento, formato esperado de cada um e regras de validação.

术语表

Termos, siglas, status e campos que aparecem na Pix Processamento. Se você ficou travado em uma sigla do Bacen ou um campo da API, é aqui. Tudo em PT com o nome original quando relevante.

本页内容

按来源划分的 HTTP通用收款 / Cash-in提现 / Cash-out内部转账Pix 密钥 / DICT / QR查询 / 凭证 / 账户违规（MED）金融机构通用错误