エラー - Auxia Docs

日本語版はAIによる翻訳です。正確な情報については英語版をご参照ください。

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

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

エラーレスポンス

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

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

{
  "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 レスポンスは標準のエラーボディを返します。

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

レート制限

Insert Treatment および Update Treatment には、プロジェクト単位のレート制限が設定される場合があります。上限を超えると、APIは以下のヘッダーとともに 429 を返します。

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

エラー処理のテスト

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

​エラーレスポンス

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

​サーバーエラー

​エラーへの対処

​リトライの安全性

​レート制限

​エラー処理のテスト

エラーレスポンス

HTTPステータスコード一覧

サーバーエラー

エラーへの対処

リトライの安全性

レート制限

エラー処理のテスト