エラーハンドリング設計

外部システム側で本APIと連携する際に、事前に想定しておきたいエラーの種類と、設計上の注意点をまとめます。個別のエラーメッセージ一覧はエラーコード一覧を参照してください。

基本方針

本APIのエラーは、エンドポイントに共通して、以下のHTTPステータスコードで表現されます。

ステータス	意味
`400 Bad Request`	リクエストパラメータが不正、または要求が無効
`401 Unauthorized`	認証に失敗（アクセストークンが無効・期限切れ、または `client_id` / `client_secret` の組み合わせが正しくない場合等）
`403 Forbidden`	`User-Agent` ヘッダー未設定等によるブロック（詳細は User-Agentヘッダーに関する注意を参照）
`404 Not Found`	存在しないURLへのリクエスト、または外部連携ID削除で指定した顧客IDが存在しない場合
`405 Method Not Allowed`	許可されていないHTTPメソッドでのリクエスト
`500 Internal Server Error`	想定外のサーバーエラー

エラーレスポンスの形式は、大きく次の3種類に整理できます。いずれの形式も status: false を含みます。

形式A：業務エラー（`400`）

errors が文字列で返却されます。指定した顧客ID・ユニークID・外部連携ID・ポイント付与IDなどが存在しない場合や、契約が無効な場合など、エンドポイント固有の業務エラーで使われます。

{ "status": false, "errors": "Member is not found" }

形式B：入力チェックエラー（`400`）

errors が文字列の配列で返却されます。リクエストパラメータのバリデーションエラー（必須項目の欠落、重複など）で使われ、複数のエラーが同時に返る場合があります。

{
  "status": false,
  "errors": [
    "指定のunique idは既に使用されています。",
    "passwordは必須です。"
  ]
}

形式C：共通エラー（`401` / `404` / `405` / `500`）

error_code（機能ごとの一意なコード）を含む、構造化された形式で返却されます。

{
  "status": false,
  "errors": "Page Not Found",
  "all_errors": ["Page Not Found"],
  "error_code": "API-OPENAPI08"
}

HTTPステータス	`errors`	`error_code`
`401 Unauthorized`	`["認証に失敗しました。"]`（配列）	`API-OPENAPI16`
`404 Not Found`	`"Page Not Found"`（文字列）	`API-OPENAPI08`
`405 Method Not Allowed`	エラーメッセージ（文字列）	`API-OPENAPI09`
`500 Internal Server Error`	`"Internal Server Error"`（文字列）	`API-OPENAPI21`

形式Cの中で 401 のみ errors が配列で返却される点に注意してください。

将来的に全エンドポイントで構造化形式に統一される可能性もあるため、外部システム側では両方の形式に対応できるようパース処理を実装することを推奨します。個別のエラーメッセージ一覧はエラーコード一覧を参照してください。

アクセストークンが無効な場合のレスポンスヘッダーに関する注意

アクセストークンが無効な場合の 401 は、レスポンスボディはJSONですが、Content-Type が text/html; charset=UTF-8 で返却されます（WWW-Authenticate: Bearer error="invalid_token" ヘッダーも付与されます）。Content-Type の値でJSONパースの可否を判定する実装では、エラー内容を正しく取得できない場合があるため注意してください。

レート制限超過時の挙動

推奨利用頻度（1分間2000リクエスト以下）を超過した場合、現状は明示的なエラー（429 Too Many Requests 等）は返却されません。ただし、将来的に制限が強化される可能性があるため、外部システム側では推奨頻度を超えないよう、直列（シーケンシャル）でのAPIコールを設計してください。詳細はレート制限とリトライ設計を参照してください。

User-Agentヘッダーに関する注意

アクセストークン取得APIを含む、すべてのエンドポイントで User-Agent ヘッダーの設定が必須です。未設定・空文字列のリクエストによってブロックされた場合、HTTPステータス 403 とともにHTML形式のエラーページ（Content-Type: text/html）が返却されます。通常のAPIエラーと異なり、JSONボディ（status / errors）は含まれません。

サーバー間連携で使用するHTTPクライアントの中には、初期設定では User-Agent が空になるものがあります（例：PHPの curl コマンドや file_get_contents 関数など）。外部システムからリクエストする際は、必ず具体的な User-Agent 値（システム名やバージョンが分かるもの、例：YourSystemName/1.0）を設定してください。