概览
錯誤處理分两层：先看 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 不应原样重试。