跳转到主要内容

​
概览

错误处理分两层：先看 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 不应原样重试。