概览
错误处理分两层：先看 HTTP 状态码，再看可选的error.code。字段名和错误码是 API 契约，因此在所有语言中保持不变。
响应格式
{
"error": {
"code": "PLAN_FEATURE_NOT_ENABLED",
"message": "Feature is not enabled for this plan",
"details": { "feature": "workflowAutomation" }
}
}
HTTP
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | JSON、字段、选项、人机验证、文件输入或金额校验错误。 | 修正请求数据后再重试。 |
| 401 | 令牌缺失/无效、凭证错误、MFA 失败、刷新令牌吊销，或租户/用户/成员/角色停用。 | 重新认证或恢复访问。 |
| 403 | 已认证，但被权限、主体范围、计划权益、容量、来源或 API 签名阻止。 | 授权、升级计划或修正请求完整性配置。 |
| 404 | 资源不存在、已删除、跨租户，或被范围隐藏。 | 检查 id 和调用方范围。 |
| 409 | 唯一值已存在。 | 更换值或读取已有资源。 |
| 422 | 请求格式正确但违反业务规则，如工作流门禁、动态字段、导入限制或必需证据。 | 补齐业务条件后重试。 |
| 429 | 触发限流。 | 退避后重试，避免并发重试。 |
| 500 | 未处理服务端错误。 | 写操作重试前先确认原操作是否已生效。 |
| 503 | 依赖服务暂时不可用。 | 幂等读取可退避重试；写操作先查状态。 |
计划与配额
| 错误码 | 处理方式 |
|---|---|
PLAN_CONTRACT_LIMIT_EXCEEDED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
PLAN_SEAT_LIMIT_EXCEEDED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
PLAN_STORAGE_LIMIT_EXCEEDED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
PLAN_FEATURE_NOT_ENABLED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
PLAN_SUBSCRIPTION_REQUIRED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
PLAN_SUBSCRIPTION_INACTIVE | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
PLAN_NOT_AVAILABLE | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
文件与上传
| 错误码 | 处理方式 |
|---|---|
FILE_NAME_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_SIZE_EMPTY | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_TOO_LARGE | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_CONTENT_TYPE_NOT_ALLOWED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_EXTENSION_NOT_ALLOWED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_KIND_NOT_ALLOWED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_REF_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_KIND_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_SCAN_NOT_CLEAN | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_SCAN_REQUEST_FAILED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
FILE_BINDING_CONTEXT_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_OBJECT_KEY_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_OBJECT_NOT_FOUND | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_OBJECT_SIZE_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_OBJECT_TYPE_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_OBJECT_CHECKSUM_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_TOKEN_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_TOKEN_EXPIRED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UPLOAD_METADATA_MISMATCH | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
金额与发票
| 错误码 | 处理方式 |
|---|---|
AMOUNT_REQUIRED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
AMOUNT_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
AMOUNT_UNSAFE_NUMBER | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
AMOUNT_OUT_OF_RANGE | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
AMOUNT_SCALE_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
UNSUPPORTED_CURRENCY | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
INVOICE_AMOUNT_EXCEEDS_TARGET | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
合同与工作流
| 错误码 | 处理方式 |
|---|---|
OWNER_SCOPE_RESTRICTED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
ASSIGNEE_NOT_ACTIVE_TENANT_MEMBER | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
SUBJECT_NOT_FOUND | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
CONTRACT_TYPE_NOT_CONFIGURED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
LIFECYCLE_STAGE_NOT_CONFIGURED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
LIFECYCLE_TEMPLATE_NOT_AVAILABLE | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
DYNAMIC_FIELDS_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
DYNAMIC_FIELD_UNKNOWN | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
DYNAMIC_FIELD_REQUIRED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
DYNAMIC_FIELD_TYPE_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
DYNAMIC_FIELD_OPTION_INVALID | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
CONTRACT_PDF_REQUIRED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
REQUIRED_FIELDS_MISSING | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
CONTRACT_CORE_FIELDS_LOCKED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_FIELDS_REQUIRE_TRANSITION | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_REQUIRED_FIELDS_MISSING | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_REQUIRED_EVIDENCE_MISSING | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_AI_REVIEW_PENDING | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_FULFILLMENT_OPEN | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_RECEIVABLES_OPEN | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
WORKFLOW_NOTE_REQUIRED | 根据 HTTP 状态、message 和 details 展示需要修正的内容；修正后再重试。 |
重试
- 幂等 GET 和 503 读取可退避重试。
- POST、PATCH、DELETE 超时或 5xx 后，先检查当前资源状态再决定是否重试。
- 400、401、403、404、409、422 不应原样重试。