> 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/ja/preparation/status-code.md).

# ステータスコード

本ページでは、API で MaiAgent サービスと連携する際に返される HTTP ステータスコードと、レスポンス形式の例を紹介します

API で HTTP リクエストを送信する際は、以下のステータスコードでリクエストが成功したかどうかを確認できます：

## ステータスコードの説明

### 成功コード

| ステータスコード | 説明                                |
| -------- | --------------------------------- |
| 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" %}
エラーレスポンスには主に 3 つの形式があります。`detail` オブジェクト（例：`{"detail": "…"}`。一部には `code` も含まれます）、フィールドオブジェクト（キーは camelCase のフィールド名）、文字列の配列です。AI Gateway の OpenAI 互換エンドポイントは、OpenAI 形式の `error` オブジェクトを使用します。処理はステータスコードと `code` に基づいて判断し、`detail` の文字列を照合しないでください。各ステータスコードの詳しい説明と対処方法は [API 共通仕様：エラーレスポンス](/api/ja/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` には 3 つの場合があり、「有効な有料プランがない」場合にのみ `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](/api/ja/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 キーの 1 分あたりのリクエスト数（RPM）やエンドポイント自体の固定上限を超えると、`429` と `Retry-After` ヘッダー（秒数）を返します：

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

`Retry-After` に指定された秒数だけ待ってから再試行し、すぐに再送しないでください。制限の適用範囲は [API 共通仕様：レート制限](/api/ja/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/ja/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.