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

# エラー

> Auxia APIのHTTPステータスコード、エラーレスポンスの形式、リトライのガイダンス。

<Note>
  日本語版はAIによる翻訳です。正確な情報については[英語版](/api-reference/errors)をご参照ください。
</Note>

Auxiaは、APIリクエストの成功・失敗を一般的なHTTPレスポンスコードで示します。概要は以下のとおりです。

* `2xx` 番台のコードは成功を示します。
* `4xx` 番台のコードは、必須フィールドの欠落、無効なAPIキー、存在しないリソースの参照など、リクエストに起因するエラーを示します。`429` を除き、同じリクエストを再送しても成功しません。
* `5xx` 番台のコードは、Auxia側のエラーを示します。発生はまれで、通常はリトライが可能です。

## エラーレスポンス

API本体が返すすべてのエラーレスポンスは、以下の属性を持つ `application/json` のボディを返します。

| 属性 | 型 | 説明 |
| - | - | - |
| `code` | Integer | レスポンスのHTTPステータスコード。ステータスラインの値と常に一致します。 |
| `message` | String | エラーの内容を説明する文字列。開発者向けの情報であり、内容は変更される可能性があります。パースしたり、条件分岐に使用したりしないでください。 |

```json theme={null}
{
  "code": 400,
  "message": "user_id must be set in request"
}
```

一部のメッセージの末尾には、`Reference A0D3427F89CACF13.F26AB72FAA88C751` や `[ID: 66A1855B08B0DF57.057CA4DCB18714FF; ...]` のような参照IDが含まれます。失敗したリクエストについてAuxiaにお問い合わせいただく際は、この参照IDをお知らせください。

## HTTPステータスコード一覧

| コード | 名称 | 説明 |
| - | - | - |
| 200 | OK | リクエストは成功しました。 |
| 400 | Bad Request | リクエストが無効です。必須フィールドの欠落、値の形式の誤り、ボディが有効なJSONでないことなどが主な原因です。 |
| 403 | Forbidden | APIキーが指定されていない、無効である、またはこのプロジェクトでこのAPIを呼び出す権限がありません。AuxiaはAPIキーに関するすべてのエラーで `403` を返します。`401` は返しません。 |
| 404 | Not Found | プロジェクト、またはリクエストで参照しているその他のリソースが存在しません。存在しないAPIパスを呼び出した場合にも返されます。 |
| 405 | Method Not Allowed | `POST` 以外のHTTPメソッドでAPIが呼び出されました。 |
| 409 | Conflict | リクエストが既存のリソースと競合しています。例えば、同じ `external_treatment_id` を持つトリートメントがすでに存在する場合です。 |
| 413 | Payload Too Large | リクエストボディが1 MiB（Insert TreatmentおよびUpdate Treatmentでは16 MiB）を超えています。 |
| 429 | Too Many Requests | プロジェクトがこのAPIのリクエストレート上限を超えました。[レート制限](#レート制限)を参照してください。 |
| 500 | Internal Server Error | Auxia側で予期しないエラー、または内部のタイムアウトが発生しました。 |
| 502 | Bad Gateway | Auxiaのロードバランサーが、APIからレスポンスを受け取れませんでした。 |
| 503 | Service Unavailable | Auxiaが一時的にリクエストを処理できない状態です。 |
| 504 | Gateway Timeout | APIゲートウェイが制限時間内にレスポンスを受け取れませんでした。 |

## サーバーエラー

`500` レスポンスは標準のエラーボディを返します。

```json theme={null}
{
  "code": 500,
  "message": "An unexpected error occurred; please contact Auxia for more information. [ID: 66A1855B08B0DF57.057CA4DCB18714FF; MI: 16DBD8420A570FAA; P: auxia-gcp]"
}
```

Auxia内部でタイムアウトが発生した場合も `500` が返され、メッセージに `error code E4896` が含まれます。

API本体が返す `503` および `504` レスポンスも同じ形式です。

API本体ではなくAuxiaのロードバランサーが返す `5xx` レスポンスは、`text/html` のボディになります。以下は `502` の例です。

```html theme={null}
<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>502 Server Error</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Server Error</h1>
<h2>The server encountered a temporary error and could not complete your request.<p>Please try again in 30 seconds.</h2>
<h2></h2>
</body></html>
```

サーバーエラーはボディではなく、ステータスコードで判定してください。

## エラーへの対処

| コード | リトライ | 対処方法 |
| - | - | - |
| 400, 404, 405, 413 | 不可 | リクエストを修正してください。`message` に問題の内容が示されます。 |
| 403 | 不可 | APIキーが正しいこと、`x-api-key` ヘッダーで送信されていること、このAPIに必要な種類のキーであることを確認してください。 |
| 409 | 不可 | リソースはすでに存在します。既存のリソースを取得するか、挿入ではなく更新を行ってください。 |
| 429 | 可 | `Retry-After` ヘッダーに示された秒数だけ待ってからリトライしてください。 |
| 500 | リトライ可能なAPIであれば可 | 指数バックオフで、少ない回数に限ってリトライしてください。エラーが続く場合は、参照IDを添えてAuxiaにお問い合わせください。 |
| 502, 503, 504 | リトライ可能なAPIであれば可 | 指数バックオフとジッターを用いてリトライしてください。 |

リトライ時は、ジッター付きの指数バックオフを使用してください。最初のリトライまで約1秒待ち、試行ごとに待機時間を2倍にし、ランダムな遅延を加えます。障害が長引いた際にトラフィックが増幅しないよう、試行回数には上限を設けてください。

### リトライの安全性

`5xx` エラーで失敗したリクエストや、クライアント側でタイムアウトしたリクエストも、サーバー側では処理済みの可能性があります。データを書き込むリクエストをリトライする前に、重複が問題にならないか確認してください。

| API | リトライ | 備考 |
| - | - | - |
| [Get Treatments](/ja/api-reference/get-treatments) | 可 | 呼び出しごとに新しい判定が行われ、新しい `responseId` が発行されます。表示には、実際に使用したレスポンスのトリートメントを使ってください。 |
| [Get Treatment](/ja/api-reference/treatment-management/get-treatment)、[Get All Treatments](/ja/api-reference/treatment-management/get-all-treatments)、[Get DataFields](/ja/api-reference/treatment-management/get-datafields) | 可 | 読み取り専用です。 |
| [Insert Surface](/ja/api-reference/treatment-management/insert-surface)、[Insert Data Field](/ja/api-reference/treatment-management/insert-data-field) | 可 | 冪等です。既存の項目を挿入すると、既存の項目が返されます。 |
| [Insert Treatment Type](/ja/api-reference/treatment-management/insert-update-treatment-type) | 可 | 同一のリクエストでは既存のトリートメントタイプが返されます。同じ名前で内容が異なるリクエストは `409` を返します。 |
| [Update Treatment Type](/ja/api-reference/treatment-management/insert-update-treatment-type)、[Update Treatment](/ja/api-reference/treatment-management/insert-update-treatment) | 可 | 同じ更新を繰り返しても結果は変わりません。 |
| [Insert Treatment](/ja/api-reference/treatment-management/insert-update-treatment) | `external_treatment_id` 指定時のみ可 | `external_treatment_id` を指定すると、すでに成功した挿入をリトライした場合に、2つ目のトリートメントが作成されず `409` が返されます。 |
| [Log Treatment Interaction](/ja/api-reference/log-treatment-interactions) | 注意が必要 | インタラクションは重複排除されません。すでに成功したリクエストをリトライすると、インタラクションが二重に記録される可能性があります。 |
| [Log Events](/ja/api-reference/log-events) | `insertId` 指定時のみ可 | リトライしたイベントを重複排除できるよう、各イベントに `insertId` を設定してください。 |

## レート制限

[Insert Treatment](/ja/api-reference/treatment-management/insert-update-treatment) および [Update Treatment](/ja/api-reference/treatment-management/insert-update-treatment) には、プロジェクト単位のレート制限が設定される場合があります。上限を超えると、APIは以下のヘッダーとともに `429` を返します。

| ヘッダー | 説明 |
| - | - |
| `Retry-After` | リトライまでに待機する秒数。 |
| `X-RateLimit-Limit` | プロジェクトに許可されている1秒あたりの最大リクエスト数。 |
| `X-RateLimit-Remaining` | 現在のウィンドウで残っているリクエスト数。 |

## エラー処理のテスト

エラー処理をテストする際は、お客様のテスト環境でAuxia APIのスタブを用意し、このページに記載したステータスコードとボディを返すようにしてください。Auxiaは、サーバーエラーを任意に発生させる機能を提供していません。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.