> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/preparation/status-code.md).

# 狀態碼

本篇將介紹使用 API 串接 MaiAgent 服務時，不同狀態下會回傳的 HTTP 代碼與回傳格式範例

在透過 API 送出 HTTP 請求時，可使用以下狀態碼查看 API 請求成功與否：

## 狀態碼說明

### 正確代碼

| 狀態碼 | 說明                 |
| --- | ------------------ |
| 200 | 請求成功               |
| 201 | 資源成功建立             |
| 204 | 請求成功，沒有回應內容（常見於刪除） |

#### 正確回應範例

{% hint style="info" %}
此處為內容示範，不同端點的回傳格式內容可能有差異，請以該端點的說明文件參考為主
{% endhint %}

```json
{
  "count": "integer",
  "next": "string|null",
  "previous": "string|null",
  "results": [
    // 結果回傳內容
  ]
}
```

### 錯誤代碼

| 狀態碼 | 說明                                             |
| --- | ---------------------------------------------- |
| 400 | 請求格式錯誤                                         |
| 401 | 認證失敗                                           |
| 402 | 方案、Credits 或額度不足，見 [402 回應](#payment-required) |
| 403 | 權限不足                                           |
| 404 | 資源不存在                                          |
| 409 | 與資源目前的狀態衝突，見 [409 回應](#conflict)               |
| 429 | 超過速率限制，見 [429 回應](#too-many-requests)          |
| 500 | 伺服器錯誤                                          |

{% hint style="info" %}
錯誤回應的內容主要有三種形狀：`detail` 物件（例如 `{"detail": "…"}`，少數會多帶 `code`）、欄位物件（key 是 camelCase 欄位名）、字串陣列；AI Gateway 的 OpenAI 相容端點則使用 OpenAI 格式的 `error` 物件。處理時請依狀態碼與 `code` 判斷，不要比對 `detail` 文字。各狀態碼的完整說明與處理建議見 [API 共通規範：錯誤回應](https://docs.maiagent.ai/api/preparation/conventions.md#errors)。
{% endhint %}

#### 錯誤回應範例

#### <mark style="background-color:$primary;">400 - 請求錯誤：必填欄位缺失</mark>

```javascript
{
  "files": ["This field is required."],
  "filename": ["This field is required."],
  "file": ["This field is required."]
}
```

#### <mark style="background-color:$primary;">402 - 方案、Credits 或額度不足</mark> <a href="#payment-required" id="payment-required"></a>

`402` 有三種情況，只有「沒有有效的付費方案」會帶 `code`：

| 情況                       | `code`           |
| ------------------------ | ---------------- |
| 組織沒有有效的付費方案              | `no_active_plan` |
| 組織 Credits 不足            | 無                |
| 成員的個人額度用完或未分配，或所屬角色的額度用完 | 無                |

```json
{
  "detail": "Your organization has no active paid plan. Please upgrade to continue using the platform.",
  "code": "no_active_plan"
}
```

```json
{
  "detail": "Insufficient credits for KB search. Please top up your account."
}
```

Credits 不足與額度用完的回應只有 `detail`，文字依端點與語系而異，無法從回應內容分辨是哪一種，請組織管理者到後台確認。AI Gateway 端點的格式不同，見 [API 共通規範：402](https://docs.maiagent.ai/api/preparation/conventions.md#payment-required)。

#### <mark style="background-color:$primary;">409 - 與資源目前的狀態衝突</mark> <a href="#conflict" id="conflict"></a>

請求與資源目前的狀態衝突，例如同一件工作已在執行中，或要刪除的資源仍被其他資源引用。回應是 `detail` 物件，部分端點會附上處理所需的欄位：

```json
{
  "detail": "An FAQ import is already running for this knowledge base.",
  "jobId": "…"
}
```

請先讀回資源的最新狀態再決定下一步，不要原樣重送。

#### <mark style="background-color:$primary;">429 - 超過速率限制</mark> <a href="#too-many-requests" id="too-many-requests"></a>

超過 API Key 的每分鐘請求數（RPM）或端點本身的固定上限時回 `429`，並帶 `Retry-After` 標頭（秒數）：

```json
{
  "detail": "Request was throttled. Expected available in 42 seconds."
}
```

請依 `Retry-After` 的秒數退避後再重試，不要立刻重送。哪些範圍會限流見 [API 共通規範：速率限制](https://docs.maiagent.ai/api/preparation/conventions.md#rate-limits)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/preparation/status-code.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
