错误处理

所有 API 错误响应均遵循标准 JSON 格式，以便于程序化处理。

错误格式

{
  "errorCode": "missing_tenant",
  "message": "X-Tenant-Id header is required"
}

通用错误目录

错误代码	HTTP	说明
missing_tenant	400	X-Tenant-Id 请求头是必需的，但未提供。
missing_idempotency_key	400	该操作需要 Idempotency-Key 请求头。
invalid_payload	400	请求体（JSON）无效或包含验证错误。
idempotency_conflict	409	该幂等性密钥已被用于不同的请求体。
forbidden	403	您无权对请求的资源执行此操作。
invalid_signature	401	提供的签名（HMAC）无效或时间戳已过期。
authz_error	500	验证授权权限时发生内部错误。
partner_error	502	与银行提供商通信时发生错误。
internal_error	500	服务器发生意外错误。

业务特定错误

PIX Out（转账）

错误代码	HTTP	说明
insufficient_balance	400	可用余额不足以完成该操作。消息包含详情：总余额、冻结金额和请求金额。
invalid_key_type	400	提供的 keyType 无效。接受的值：CPF、CNPJ、EMAIL、PHONE、EVP。
invalid_emv	400	QR Code EMV 字符串无效或格式错误。
pix_limit_exceeded	400	交易金额超过为该账户配置的限额。

QR Codes

错误代码	HTTP	说明
pix_qr_not_found	404	请求的 QR Code 未找到或已过期。
pix_qr_already_paid	409	该动态 QR Code 已被支付。
pix_qr_expired	400	该动态 QR Code 已过期，无法再进行支付。
pix_qr_cancelled	400	该 QR Code 已被取消，无法再进行支付。

PIX 密钥

错误代码	HTTP	说明
pix_key_not_found	404	提供的 PIX 密钥未在 DICT 中找到。
pix_key_already_exists	409	该 PIX 密钥已注册到其他账户。
pix_key_limit_exceeded	400	每个账户的 PIX 密钥数量已达上限。

退款

错误代码	HTTP	说明
refund_not_allowed	400	此交易不允许退款（例如，退款期限已过）。
refund_amount_exceeded	400	退款金额超过原始交易金额。
original_transaction_not_found	404	原始交易（originalEndToEnd）未找到。

MED（特殊退回机制）

错误代码	HTTP	说明
med_not_found	404	指定的 MED 未找到。
med_already_answered	409	该 MED 已被回复。
med_deadline_expired	400	回复该 MED 的截止时间已过。

常见错误示例

余额不足

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

无效的密钥类型

{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}

幂等性冲突

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

无效的 EMV

{
  "errorCode": "invalid_payload",
  "message": "emv is required"
}

监控与支持

如果您频繁收到 5xx 错误（内部错误或合作伙伴错误），我们建议：

1. 实现指数退避重试，使用相同的幂等性密钥（最多 3 次尝试）。
2. 检查平台状态，以应对长时间不可用的情况。
3. 联系支持团队，并提供以下信息：
   • 收到的 errorCode
   • 发送的请求体（不包含敏感数据）
   • 响应中的 X-Request-Id（如果有）
   • 错误发生的大致时间戳

支持渠道

• Slack： 每位客户专属私有频道——请在入驻流程中向 CorpX 团队申请访问权限。
• 邮箱： support@corpxapi.com