> ## 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 不应原样重试。