エラーコード一覧

本APIで発生する主なエラーの一覧です。エンドポイントごとの詳細なバリデーションエラーについては、順次拡充予定です（設計方針はエラーハンドリング設計ガイドを参照）。

認証（`/api/ext/token`）

以下のいずれの場合も、レスポンスボディは同一です。両者の違いはHTTPステータスコードと、401の場合に付与されるWWW-Authenticateヘッダーの有無のみです。

client_id が未指定、または grant_type が client_credentials 以外の場合：400
client_id と client_secret の組み合わせが正しくない場合：401（WWW-Authenticate: Basic realm="token" ヘッダーが付与されます）

{
  "status": false,
  "errors": ["認証に失敗しました。"],
  "all_errors": ["認証に失敗しました。"],
  "error_code": "API-OPENAPI16"
}

共通（顧客・ポイント系エンドポイント全般）

HTTPステータス	説明
`400 Bad Request`	リクエストパラメータが不正です
`401 Unauthorized`	アクセストークンが無効、または有効期限切れです
`404 Not Found`	存在しないURLへのリクエスト、または外部連携ID削除で指定した顧客IDが存在しない場合
`405 Method Not Allowed`	許可されていないHTTPメソッドでのリクエスト
`500 Internal Server Error`	想定外のサーバーエラー

アクセストークンが無効な場合

401の場合、あわせて以下の構造化されたエラーが返却されます。

{
  "status": false,
  "errors": ["認証に失敗しました。"],
  "all_errors": ["認証に失敗しました。"],
  "error_code": "API-OPENAPI16"
}

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

契約が無効な場合

クライアント（契約）が無効な状態の場合、全エンドポイント共通で以下のエラーが返却されます。

{
  "status": false,
  "errors": "Not contracted"
}

指定した顧客ID・ユニークID・外部連携IDが存在しない場合

顧客詳細系・顧客更新・ログアウト・ポイント系の各エンドポイントでは、指定した顧客ID・ユニークID・外部連携IDが存在しない場合、以下のエラーが返却されます。errors はエンドポイントによって配列または文字列のいずれかで返るため、両方に対応したパース処理にしてください。

なお、ログインAPI（POST /api/ext/users/login）は顧客ID・ユニークID・外部連携IDを受け取らないため、このエラーは返却されません。存在しない login_id を指定した場合は、ログインのエラー表にある ログインIDまたはパスワードが間違っています。 が返却されます。

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

なお、未設定の external_key を顧客詳細（外部連携ID）に指定した場合も、同じ Member is not found エラーが返却されます（キー自体が存在しないケースと、指定した外部連携IDに該当する顧客が存在しないケースを区別しません）。

`point` / `amount` に不正な値を指定した場合（ポイント付与・ポイント計算）

{
  "status": false,
  "errors": ["pointには、整数を指定してください。"]
}

ポイント計算（amount）の場合も同様に、以下のエラーが返却されます。

{
  "status": false,
  "errors": ["amountには、整数を指定してください。"]
}

保有ポイントが不足している場合（ポイント付与）

ポイント付与で point に負の値（減算）を指定し、保有ポイントが不足している場合、以下のエラーが返却されます。errors がフィールド名をキーにしたオブジェクト形式で返却される点に注意してください（他の業務エラーは文字列または配列で返却されます）。

{
  "status": false,
  "errors": {
    "point": ["保有ポイントが不足しています。"]
  }
}

ポイント機能を利用していない場合（ポイント付与・ポイント計算）

ポイント機能を利用していないクライアントで、ポイント付与またはポイント計算を呼び出した場合、以下のエラーが返却されます。

{
  "status": false,
  "errors": "Not available for points"
}

許可されていないHTTPメソッドでリクエストした場合

HTTPステータス：405

{
  "status": false,
  "errors": "...",
  "all_errors": ["..."],
  "error_code": "API-OPENAPI09"
}

想定外のサーバーエラーが発生した場合

HTTPステータス：500

{
  "status": false,
  "errors": "Internal Server Error",
  "all_errors": ["Internal Server Error"],
  "error_code": "API-OPENAPI21"
}

顧客登録・更新（`POST` / `PUT` `/api/ext/users`）

エラー時は status: false と errors を含むJSONが返却されます。errors は配列または文字列のいずれかで返るため、両方に対応したパース処理にしてください。

エラーメッセージ	意味
`指定のunique idは既に使用されています。`	`unique_id` が重複
`指定のlogin idは既に使用されています。`	`login_id` が重複
`external_ids.〇〇の値は既に使用されています。`	指定した外部連携ID（`external_ids`）の値が、同一クライアント内の他の顧客と重複
`passwordは必須です。`	必須フィールドの不足（例：パスワード）。クライアント設定によっては必須化されている場合があります
`loginedが1の場合、logined atを指定してください。`	`logined=1` を指定したが `logined_at` が未指定
`会員情報の保持に必要なカスタムフィールドの設定がありません。`	カスタムフィールドの設定不足

契約が無効な場合に返却される Not contracted エラーについては、共通のエラーを参照してください。

外部連携ID削除（`DELETE /api/ext/users/{id}/external_ids/{key}`）

存在しない id を指定した場合、他のエンドポイントとは異なり 404 と以下のエラーが返却されます。

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

顧客は存在するが、指定した key の外部連携IDが登録されていない場合は、400 と以下のエラーが返却されます。

{
  "status": false,
  "errors": "External ID not found"
}

引き継ぎトークンチェック（`GET /api/ext/check/{token}`）

トークンが期限切れの場合、以下のエラーが返却されます。

{
  "status": false,
  "errors": "Token is expired"
}

存在しない・使用済み・id が一致しないなど、その他の不正な token を指定した場合、以下のエラーが返却されます。

{
  "status": false,
  "errors": "Invalid Token"
}

レート制限

推奨利用頻度（1分間2000リクエスト以下）を超過した場合でも、現状 429 Too Many Requests 等の専用エラーは返却されません。詳細はレート制限とリトライ設計ガイドを参照してください。

構造化エラーレスポンスについて

アクセストークン無効時（401）や外部連携ID削除の404など、一部のエラーでは status / errors（メッセージ配列） / all_errors / error_code（一意なエラーコード）を含む、より構造化された形式が使用されています。一方で、顧客登録・更新時のバリデーションエラー等は現状 status / errors のみのシンプルな形式です。将来的に全エンドポイントで構造化形式に統一される可能性があるため、外部システム側では両方の形式に対応できるようパース処理を実装することを推奨します。

認証（/api/ext/token）