> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码

> Alforse API 的 HTTP 状态码、业务错误码和处理建议。

## 概览

错误处理分两层：先看 HTTP 状态码，再看可选的 `error.code`。字段名和错误码是 API 契约，因此在所有语言中保持不变。

## 响应格式

```json theme={null}
{
  "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 不应原样重试。