错误代码

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

按来源划分的 HTTP

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

代码	HTTP	消息	处理方式
`PZV001`	400	Dados inválidos. Verifique os campos informados.	查看 `details[]`：指明字段和原因。
`PZI100`	500	Erro interno ao processar a solicitação.	重试；若持续，携带 `requestId` 联系支持团队。
`PZA100`	401	Autenticação necessária ou token inválido.	发送有效且有效期内的 `Authorization: Bearer`。
`PZA200`	403	Operação não permitida para este token/escopo.	Token 不具备该路由所需的权限，或访问的子域与账户不匹配。
`PZA203`	403	Acesso não permitido a partir deste endereço de IP.	IP 不在白名单内（提现/转账）。在配置中放行该 IP。

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

代码	HTTP	消息	处理方式
`PZD200`	422	Depósito não permitido para esta conta.	收款未开通；联系支持团队。
`PZD201`	422	Depósitos de CNPJ não estão liberados para esta conta.	CNPJ 付款方未开通。
`PZD500`	503	Nenhuma instituição financeira disponível no momento. Tente novamente em instantes.	在 `retryAfterSeconds` 后重试。
`PZD600`	400	O valor mínimo do depósito é `{min}`.	金额低于最小值。
`PZD601`	400	O valor máximo do depósito é `{max}`.	金额高于最大值。
`PZD602`	400	Para depósitos acima de `{limite}` é obrigatório informar o documento.	发送 `generatedDocument`。
`PZD100`	502	Não foi possível gerar o depósito junto à instituição financeira. Tente novamente.	收款方故障；重试。

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

代码	HTTP	消息	处理方式
`PZS200`	422	Saque não permitido para esta conta no momento.	提现未开通。
`PZS500`	503	Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes.	在 `retryAfterSeconds` 后重试。
`PZS600`	400	O valor mínimo do saque é `{min}`.	金额低于最小值。
`PZS601`	400	O valor máximo do saque é `{max}`.	金额高于最大值。
`PZS602`	400	O valor do saque está fora dos limites da instituição financeira.	调整到收款方的限额内。
`PZS603`	400	O valor informado (`{a}`) não corresponde ao valor do QR Code (`{b}`).	使用 QR 中的确切金额。
`PZS604`	400	É obrigatório informar o valor.	QR 无固定金额；请提供金额。

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

代码	HTTP	消息	处理方式
`PZK101`	502	Não foi possível consultar o QR Code junto à instituição financeira.	重试。
`PZK200`	422	Chave Pix inválida.	密钥无效。
`PZK201`	422	A chave Pix não corresponde ao documento do destinatário.	密钥与文件不匹配。
`PZK300`	404	Chave Pix não encontrada.	在 DICT 中未找到密钥。
`PZK301`	404	QR Code não encontrado.	未找到 QR。
`PZK310`	410	Este QR Code expirou ou foi removido pela instituição financeira recebedora.	请求新的 QR。
`PZK400`	403	Consulta de chave Pix não habilitada para o usuário.	未开通；联系支持团队。
`PZK401`	403	Leitura de QR Code não habilitada para o usuário.	未开通。
`PZK600`	400	Chave Pix inválida. Formatos: CPF, CNPJ, e-mail, telefone (+55...) ou aleatória (UUID).	修正格式。
`PZK601`	400	QR 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	消息	处理方式
`PZC210`	409	Já existe uma operação com este identificador. Verifique o clientReference informado.	`clientReference` 重复；改用其他值或查询该操作。
`PZC310`	404	Transação não encontrada.	在你的账户下未找到。
`PZC320`	422	Transação ainda não processada.	处于待处理状态时凭证不可用。
`PZC321`	422	Comprovante indisponível: transação cancelada sem documento.	交易已取消且无凭证。
`PZI103`	500	Dado interno ausente para concluir a operação.	稍后重试；若持续，携带 `requestId` 联系支持团队。

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

代码	HTTP	消息	处理方式
`PZI101`	500	Operação não suportada para esta instituição financeira.	收款方不支持该操作。
`PZI110`	502	Erro de comunicação com a instituição financeira.	重试。
`PZI111`	504	A instituição financeira demorou para responder. Tente novamente.	超时；重试。
`PZF500`	503	Instituição financeira temporariamente indisponível. Tente novamente em instantes.	在 `retryAfterSeconds` 后重试。

代码	HTTP	消息	处理方式
`PZG404`	404	Recurso não encontrado.	资源不存在。
`PZG429`	429	Muitas requisições em curto período. Tente novamente em instantes.	等待 `retryAfterSeconds`。