错误处理

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

错误格式

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

稳定的契约是 errorCode——请以它为判断依据。message 仅用于展示（葡萄牙语），可能在不通知的情况下改写。

当错误来自清算机构（我们的银行合作方）时，响应还会包含 partner 区块，内含其原始错误码与消息，便于您自行排查而无需提交工单：

{
  "errorCode": "limit_exceeded_daily",
  "message": "O valor excede o limite diurno desta conta. Limite restante: R$ 0,00.",
  "partner": {
    "code": "request.query.daily_limit_exceeded",
    "message": "O valor R$ 1.000,00 excede seu limite diurno de pagamentos por Pix. Limite restante: R$ 0,00"
  }
}

partner 区块仅供参考：请用于日志与客服沟通，切勿作为代码中的判断依据。它可能包含 code、message 与 field（清算机构指出的字段），当清算机构未提供细节时会被省略。

通用错误目录

错误代码	HTTP	说明
`missing_tenant`	400	`X-Tenant-Id` 请求头是必需的，但未提供。
`tenant_mismatch`	403	`X-Tenant-Id` 与路径中账户所属的租户（或请求体的 `tenantId`）不一致。
`tenant_forbidden`	403	该令牌未被授权访问 `X-Tenant-Id` 指定的租户。适用于所有 `/v1/` 路由：凭证与请求头必须指向同一个租户。
`tenant_suspended`	403	存在未处理的待办事项，写操作已暂停，查询仍可正常使用。请联系 CorpX 支持处理。
`tenant_disabled`	403	该租户已停用，所有 API 路由均不响应。请联系 CorpX 支持恢复访问。
`account_not_found`	404	路径中的 `accountId` 不存在。
`not_found`	404	请求的资源不存在。
`invalid_payload`	400	请求体（JSON）无效或包含验证错误。
`invalid_body`	400	请求体不是合法的 JSON。
`missing_fields` / `missing_field`	400	缺少必填字段，消息中会指明具体字段。
`invalid_field`	400	字段值超出可接受的格式或上限，消息中会指明字段与限制。
`idempotency_conflict`	409	在 `POST /v1/accreditations/biometry-evidence` 中，由 `Idempotency-Key` 推导出的 `evidenceId` 已属于其他租户。在其他端点，使用相同 `Idempotency-Key` 但不同请求体不会返回冲突：您会收到原始操作的结果。参见幂等性。
`invalid_state`	409	当前资源状态不适用于该操作。
`forbidden`	403	您无权对请求的资源执行此操作。
`unauthorized`	401	缺少 `Authorization` 头。无效或过期的令牌返回 `403`（请通过 `client_credentials` 获取新令牌）。
`insufficient_scope`	403	该凭证缺少该路由所需的权限范围（如 `qrcode.manage`、`pix_out.create`），或为只读凭证尝试写操作。错误消息会指明缺少的范围。参见身份验证指南。
`user_token_forbidden_on_financial_op`	403	用户令牌不能发起资金操作：金融类操作需要应用凭证（`client_credentials`）。
`db_unavailable` / `banking_unavailable` / `temporal_unavailable`	503	内部依赖暂时不可用，可以重试。
`db_error`	500	内部持久化错误。
`internal_error`	500	服务器发生意外错误。
`workflow_start_failed` / `workflow_signal_failed`	502	启动或通知内部流程失败；请使用相同的 `Idempotency-Key` 重试。

清算机构错误

以下是代表清算机构拒绝或失败（而非 CorpX 校验失败）的完整 errorCode 列表。该表由代码中的错误目录生成，因此不会与 API 实际返回的内容产生偏差。

两点需要注意：

HTTP 状态码是我们的，不是清算机构的。 清算机构对超限返回 403，很多客户会误读为鉴权失败；我们返回 422。同样，QR 码被移除时的 410 Gone 会转为 409，清算机构的任何 5xx 都会转为 502。
可重试表示以相同的 Idempotency-Key 重发同一请求可能得到不同结果。若为“否”，请先修正数据或前置条件再重发。

同样的错误码也会出现在失败类 webhook 的 data.errorCode 中，并附带对应的 data.partner 区块。

错误码	HTTP	发生了什么以及如何处理	可重试
`account_not_entitled`	409	该账户已完成开户，但清算机构未为其开通此项服务——同一账户的其他操作仍可正常使用。这既不是暂时性故障，也不是请求本身的问题：在清算机构完成开通之前重试无效。请携带 `accountId` 联系客服。	否
`account_not_ready`	409	该账户在清算机构尚无对应账户——开户流程仍在进行、已被拒绝或从未完成。这不是接口故障：在开户状态变为 `ACTIVE` 之前，该账户无法执行任何银行操作。	否
`already_at_partner`	409	该证件已由其他参与方在清算机构完成开户。需通过客服申请控制权转移。	否
`bacen_rejected_content`	400	文本内容（描述/消息）包含巴西央行不接受的字符。	否
`balance_reservation_failed`	422	余额预留失败（资金被锁定、正在结算或与其他操作冲突）。	否
`boleto_already_settled`	409	该票据已结算。请在重发前查询原支付记录。	否
`boleto_amount_mismatch`	422	金额与票据登记金额不符（请考虑利息、罚金与折扣）。	否
`boleto_scheduled`	409	同一条码已存在有效的预约支付。	否
`challenge_failure`	422	在清算机构的 PIN/双因素验证失败。	否
`conflict`	409	清算机构存在状态冲突（例如资源已处理）。	否
`identifier_conflict`	409	该标识符（`Identifier`）已在清算机构使用。使用相同值重发不会创建新操作。	否
`insufficient_funds`	422	清算机构在结算时判定余额不足。	否
`invalid_field`	400	清算机构的字段级校验失败。`partner.field` 指出字段名，消息中会包含限制值（如有）。	否
`invalid_payload`	400	清算机构拒绝了请求体。`partner` 区块包含原始校验信息。	否
`invalid_pix_key`	400	密钥格式与声明的类型不匹配（`CPF`、`CNPJ`、`EMAIL`、`PHONE`、`EVP`）。	否
`key_inactive`	422	密钥存在但处于未激活或携转状态。请使用其他密钥或银行账户信息。	否
`key_not_found`	404	在 DICT 中未找到该密钥。请检查输入或向收款方索取其他密钥。	否
`key_ownership_mismatch`	422	尝试注册或使用的密钥所属证件与账户持有人不一致。	否
`limit_exceeded`	422	超出限额，但清算机构未说明具体的限额窗口。	否
`limit_exceeded_daily`	422	日间时段限额（06:00–20:00）。清算机构提供时，消息中会包含剩余限额。	否
`limit_exceeded_monthly`	422	月度累计限额。仅在月度重置或提额后恢复。	否
`limit_exceeded_nightly`	422	夜间时段限额（20:00–06:00），通常低于日间限额。	否
`limit_exceeded_transaction`	422	单笔限额。请拆分操作或申请提额。	否
`not_found`	404	清算机构中不存在该资源（ID、密钥或交易）。	否
`partial_refund_not_supported`	400	旧版 — 不再返回：现已支持部分退款。金额超过原始交易时返回 `refund_amount_exceeded`。	否
`partner_account_disabled`	422	源账户在清算机构处于禁用状态（需要重新激活）。	否
`partner_error`	502	与清算机构通信时发生未分类的故障。可以重试。	是
`partner_forbidden`	502	清算机构针对该账户阻止了此操作（产品或权限未启用）。	否
`partner_internal`	502	清算机构内部错误（5xx）。可以重试。	是
`partner_rate_limited`	429	清算机构对 CorpX 的流量进行了限流。您的请求本身没有问题——请降低频率并使用退避策略重试。	是
`partner_rejected`	422	因内部政策、风控或反欺诈原因被清算机构拒绝。`partner` 区块包含其说明的原因。	否
`partner_unauthorized`	502	CorpX 在清算机构的凭证被拒绝。与您的凭证无关；请等待几分钟后再重发。	否
`partner_unavailable`	502	清算机构不可用或网关故障。可以重试。	是
`pix_key_limit_exceeded`	422	已达到每个账户的密钥数量上限（个人 5 个，企业 20 个）。	否
`qr_amount_mismatch`	422	固定金额的 QR 码不接受其他金额。	否
`qr_gone`	409	该 QR 码已在清算机构被移除或过期。	否
`recipient_account_not_found`	422	目标银行/分行/账户不存在。适用于 TED 与内部转账。	否
`refund_amount_exceeded`	400	退款金额超过原始 PIX 可退余额。	否
`timeout`	504	调用清算机构超时。操作可能已创建，请先查询再重发。	是

业务特定错误

PIX Out（转账）

错误代码	HTTP	说明
`policy_denied`	422	为该账户或 tenant 配置的策略规则拒绝了该操作 —— 转账、QR Code 创建、PIX 密钥创建或退款。响应体中的 `violations` 列出每条被违反规则的 `rule` 与 `message`。参见策略与规则。
`invalid_identifier`	400	`identifier` 超出长度上限或包含不允许的字符。
`invalid_bank_code`	400	按银行账户信息付款时，`bankCode` 接受 3 位 Compe 代码或 8 位 ISPB。TED 仅接受 Compe 代码 —— 参见 TED。
`invalid_field`	400	在发送前拦截的清算机构已知限制——`description` 超过 140 字符，或 `branch`/`accountBranch` 超过 4 位。
`dict_lookup_limit_exceeded`	429	已超出 DICT 查询限额：可能是绝对计数（`maxLookupsPerDay`、`maxLookupsPerMinute`、`maxNotFoundPer5min`），也可能是某个时间窗口的速率（每笔转账的查询次数，或未解析出密钥的查询占比，窗口从 5 分钟到 30 天）。租户/账户策略生效；未填写的字段适用全局默认值——且始终按账户计数，从不在租户层面汇总。错误消息会指明触发的是哪个计数器或哪个窗口。请等待时间窗口重置（每日限额：巴西利亚时间 00:00；速率限额为滑动窗口），或在后台管理中调整限额。`ratio`（`maxLookupRatio`）这一原因已在 v2.53.0 停用，不会再出现。
`beneficiary_not_found`	404	该收款人不存在于账户的收款人名录中。
`beneficiary_incomplete`	422	已保存的收款人缺少所选操作需要的数据。
`beneficiary_not_active_at_partner`	422	收款人已在本地登记，但尚未在清算机构生效。
`batch_too_large`	400	BigPix：请求金额会拆分成超过 99 笔。
`batch_not_found`	404	BigPix：查询的 `batchId` 不存在。

余额、限额、PIX 密钥与清算机构拒绝相关的错误使用清算机构错误一节中的错误码。

QR Code

错误代码	HTTP	说明
`missing_field`	400	缺少 `pixKey`；动态 QR 还需 `value` 且必须为正数。
`invalid_field`	400	`message` 超过 140 字符，为清算机构限制。
`invalid_identifier`	400	`identifier` 超出长度上限或包含不允许的字符。
`invalid_payload`	400	`expirationDate` 不符合 RFC 3339 格式，或已是过去时间。
`missing_param`	400	查询与取消需要 `identifier` 查询参数（别名 `txid`）。
`policy_denied`	422	策略规则拒绝了创建（`qrCode.canCreateStatic`、`qrCode.canCreateDynamic`、`qrCode.minAmount`、`qrCode.maxAmount`）。

PIX 密钥

错误代码	HTTP	说明
`invalid_body`	400	请求体不是合法的 JSON。
`missing_field`	400	缺少 `keyType`；除 `random` 外的类型还需 `pixKey`。
`invalid_pix_key`	400	无法解析路径中的密钥（邮箱与电话密钥请记得做 URL 编码）。
`policy_denied`	422	策略规则拒绝了创建（`keys.canCreate`、`keys.maxKeys`）。

密钥格式本身由清算机构校验，返回 invalid_pix_key；其每个账户的密钥数量上限返回 pix_key_limit_exceeded。

退款（PIX Refund）

错误代码	HTTP	说明
`invalid_payload`	400	`reason` 缺失或不在官方退款原因列表内。
`original_transaction_not_found`	404	原始交易（`originalEndToEnd`）未找到。

refund_amount_exceeded（金额超过原始交易，或超过剩余可退余额）来自清算机构——参见上一节。partial_refund_not_supported 不再返回：现已支持部分退款。

由 API 发起的退款同样受策略约束：退款板块被关闭（refund.disabled）或金额超过 refund.maxAmount 时返回 policy_denied（422）。

TED

错误代码	HTTP	说明
`invalid_bank_code`	400	`bankCode` 必须是 3 位 Compe 代码。TED 不接受 ISPB —— 清算机构的 TED 接口没有该字段，发送后会导致 TED 长期挂起。
`invalid_account_type`	400	`accountType` 必须是 `CHECKING`、`SAVINGS`、`PAYMENT` 或 `SALARY`。未填写时默认为 `CHECKING`。
`invalid_tax_number`	400	`taxNumber` 必须为 11 位（CPF）或 14 位（CNPJ）。
`invalid_identifier`	400	`identifier` 超出长度上限或包含不允许的字符。
`invalid_field`	400	`description` 超过 140 字符，或 `branch` 超过 4 位（请提交不含校验位的分行号）。
`missing_fields`	400	缺少 `value`、`holderName`、`branch` 或 `account`。

TED 仅按 identifier 去重且从不重新执行 —— 重复提交已使用的 identifier 会返回 200 与当前状态，失败状态亦然。参见幂等性。

内部转账

错误代码	HTTP	说明
`multiple_destination_accounts`	409	在 `/transfers/internal/by-document` 中，该证件下有多个活跃账户。请改为按账户寻址：`/transfers/internal/by-bank-account`（分行号 + 账号）或 `/transfers/internal`（`destinationAccountId`）。

清算机构的拒绝会以 422 返回，带 status: "FAILED" 与清算机构错误中的错误码 —— 通常为 insufficient_funds 或 partner_rejected。

对账单、流水与导出

错误代码	HTTP	说明
`invalid_date_range`	400	`startDate` / `endDate` 不符合 `YYYY-MM-DD` 格式。
`date_range_too_wide`	400	对账单时间跨度超过 31 天，请拆分为更短的区间。
`invalid_operation`	400	流水明细需要 `operation` 查询参数：`PIX`、`TED`、`BOLETO`、`INTERNAL` 或 `FEE`。
`invalid_query`	400	账户维度的时间线需要 `endToEndId` 与 `identifier` 中的且仅一个 —— 不能同时提供，也不能都不提供。
`invalid_format`	400	导出的 `format` 必须是 `csv` 或 `pdf`。
`not_ready`	409	在导出完成前请求下载。请轮询状态直到 `completed`。
`presign_failed`	500	为已完成的文件生成下载链接失败，可以重试。

Webhook 订阅

错误代码	HTTP	说明
`missing_field`	400	创建订阅时缺少 `url`。
`invalid_url`	400	`url` 必须使用 `https://`。
`hookdeck_sync_failed`	502	在我们的 webhook 投递服务中注册目标失败，可以重试。

开户 / 账户开立（Accreditation）

来自 POST /v1/accreditations/pf|pj、POST /v1/accreditations/biometry-evidence、POST /v1/accreditations/{id}/persons/{cpf}/retry 及查询端点的错误。

Code	HTTP	说明
`feature_disabled`	403	您的租户未启用开户（BaaS）功能。请联系 CorpX 启用。（查询仍可用。）
`missing_fields`	400	缺少必填字段（如 `documentType`、`document`、`legalName`；PF：`person.cpf`；PJ：`company.cnpj` 及至少一个 `partner`）。
`invalid_document_type`	400	`documentType` 无效——请使用 `CPF` 或 `CNPJ`。
`invalid_document`	400	证件位数不符（CPF=11，CNPJ=14）。
`invalid_field`	400	在 POST 阶段拦截的清算机构限制：`address.number` 超过 10 个字符（请将超出部分移到 `address.complement`），或 `address.cityIbgeCode` 不足 7 位 / 与 `address.state` 不一致。`address.complement` 少于 3 个字符不算错误：该字段在清算机构侧为可选，提交时会被省略。
`mixed_biometry_mode`	422	PJ：所有合伙人必须使用相同的生物识别模式（全部 `unico` 或全部 BYO），不可混用。
`unsupported_provider`	422	无法识别的 BYO 生物识别提供商。可接受：`unico`、`serpro`、`idwall`、`sumsub`、`clearsale`、`caf`、`valid`。
`provider_not_enabled`	422	该 BYO 提供商未为您的租户启用。
`evidence_not_found`	422	`biometry.evidenceId` 不存在（或不属于您的租户）。请先通过 `POST /v1/accreditations/biometry-evidence` 上传。
`not_pj`	422	公司文件上传仅接受 PJ accreditation（`POST .../documents`）。
`invalid_kind`	422	公司文件 `kind` 无效。可接受：`company_articles`、`company_proof_of_address`、`cnpj_card`、`financial_statements`、`business_license`、`regulatory_license`、`other`。
`invalid_content_type`	422	公司文件上传的 `contentType` 必须为 `application/pdf`。
`invalid_state`	409	操作不适用于当前状态（如对已通过的生物识别重试，或流程已处于终态）。
`invalid_status`	409	当前状态不允许上传公司文件（仅 `PENDING_BIOMETRY` / `BIOMETRY_APPROVED` / `PENDING_REVIEW`）。
`not_found`	404	未找到开户流程（或其中的某个人）。
`rate_limited`	429	最近一小时内针对"已有账户的 CPF"的授权请求过多。请稍后重试；持续的高频请求会由 CorpX 审查。
`presign_error`	500	为证据文件或公司文件生成上传链接失败，可以重试。
`storage_unavailable`	503	KYC 档案（证据存储桶）暂时不可用。
`workflow_signal_failed`	502	向开户流程发送信号失败；请重试。

同一批端点上的 CorpX 校验错误，文本由代码目录生成：

错误码	HTTP	发生了什么以及如何处理	可重试
`invalid_callback_uri`	400	发送的 `callbackUri` 未为您的租户登记，或不被接受（仅支持 `https://` 与应用自定义 scheme；URI 中不得含凭证、不得含 `#`、不得为 `localhost` 或内网地址）。该 URI 必须在首次使用前由 CorpX 支持团队登记，且比对为精确匹配。参见返回您的应用。	否

清算机构对开户的拒绝以异步方式送达：出现在 accreditation.failed webhook 与 GET /v1/accreditations/{id} 的 reason 字段中：

Reason	发生了什么
`partner_validation_failed`	清算机构拒绝了某个登记字段。消息中会指明字段，`partner` 区块包含原始校验信息。
`existing_partner_account`	该证件已在清算机构拥有账户——需通过客服申请控制权转移。
`partner_unavailable`	清算机构不可用。属于临时问题：请重新提交开户。
`partner_rejected`	因清算机构政策/风控原因被拒，且未指明具体字段。

常见错误示例

余额不足

{
  "errorCode": "insufficient_funds",
  "message": "Saldo insuficiente na conta do liquidante para concluir a operação.",
  "partner": {
    "code": "request.client.insufficient_balance",
    "message": "Saldo insuficiente para realizar a operação"
  }
}

字段超出清算机构限制

{
  "errorCode": "invalid_field",
  "message": "O campo \"Identifier\" não é aceito pelo liquidante com o valor enviado. O valor deve ter no máximo 50 caracteres.",
  "partner": {
    "code": "request.value.above_maximum",
    "field": "Identifier",
    "message": "O valor 'Identifier' deve ter no máximo 50 caracteres."
  }
}

幂等性冲突

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

权限范围不足

{
  "errorCode": "insufficient_scope",
  "message": "esta credencial não tem escopo para esta operação; é necessário o escopo qrcode.manage"
}

请在后台面板（API Credentials）中创建具备所需范围的凭证。涉及资金划转的范围由 CorpX 签发。

监控与支持

如果您频繁收到 5xx 错误（internal_error、partner_error、partner_unavailable、partner_internal），我们建议：

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

支持渠道

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

错误格式​

通用错误目录​

清算机构错误​

业务特定错误​

PIX Out（转账）​

QR Code​

PIX 密钥​

退款（PIX Refund）​

TED​

内部转账​

对账单、流水与导出​

Webhook 订阅​

开户 / 账户开立（Accreditation）​

常见错误示例​

余额不足​

字段超出清算机构限制​

幂等性冲突​

权限范围不足​

监控与支持​

支持渠道​