跳轉到主要內容

​
概览

錯誤處理分两层：先看 HTTP 狀態码，再看可选的 error.code。欄位名和錯誤码是 API 契约，因此在所有语言中保持不变。

​
响应格式

{
  "error": {
    "code": "PLAN_FEATURE_NOT_ENABLED",
    "message": "Feature is not enabled for this plan",
    "details": { "feature": "workflowAutomation" }
  }
}

​
HTTP

狀態码含义處理建議
400JSON、欄位、选项、人机验证、檔案输入或金额校验錯誤。修正请求資料后再重试。
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 不应原样重试。