エラーハンドリングガイド¶

概要¶

Knowledge Yard V2 APIでは、統一されたエラーハンドリングモジュール (app/api/errors.py) を使用して、一貫性のあるエラーレスポンスを提供しています。

エラーレスポンス形式¶

すべてのAPIエラーは以下の形式で返されます：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "request_id": "abc123",
    "details": {
      // Optional additional information
    }
  }
}

エラーコード¶

クライアントエラー (4xx)¶

コード	HTTPステータス	説明
`INVALID_REQUEST`	400	リクエスト形式が不正
`INVALID_JSON`	400	JSONパースエラー
`MISSING_PARAMETER`	400	必須パラメータが不足
`INVALID_PARAMETER`	400	パラメータ値が不正
`UNAUTHORIZED`	401	認証が必要
`FORBIDDEN`	403	アクセス権限がない
`NOT_FOUND`	404	リソースが見つからない
`METHOD_NOT_ALLOWED`	405	HTTPメソッドが許可されていない
`RATE_LIMITED`	429	レート制限に達した

サーバーエラー (5xx)¶

コード	HTTPステータス	説明
`INTERNAL_ERROR`	500	内部エラー
`SERVICE_UNAVAILABLE`	503	サービス一時停止
`SEARCH_ERROR`	502	Azure AI Search エラー
`OPENAI_ERROR`	502	Azure OpenAI エラー
`DATABASE_ERROR`	502	データベースエラー
`EXTERNAL_SERVICE_ERROR`	502	外部サービスエラー

例外クラス¶

基本クラス¶

from errors import APIError, ErrorCode
from http import HTTPStatus

# カスタムエラーの作成
error = APIError(
    code=ErrorCode.INVALID_REQUEST,
    message="Invalid query format",
    status=HTTPStatus.BAD_REQUEST,
    details={"field": "query", "reason": "must not be empty"}
)

便利な例外クラス¶

from errors import (
    InvalidRequestError,
    InvalidJSONError,
    MissingParameterError,
    UnauthorizedError,
    ForbiddenError,
    NotFoundError,
    SearchServiceError,
    OpenAIServiceError,
)

# パラメータ不足
raise MissingParameterError("query")

# リソースが見つからない
raise NotFoundError("User", "john_doe")

# 認証エラー
raise UnauthorizedError("Invalid token")

ルートでの使用方法¶

デコレータを使用する方法¶

from errors import handle_errors

@handle_errors("search")
def main(req: func.HttpRequest) -> func.HttpResponse:
    # エラーは自動的にキャッチされ、統一形式で返される
    ...

手動でエラーを返す方法¶

from errors import (
    error_response,
    json_response,
    get_request_id,
    validate_json_body,
    require_parameter,
    MissingParameterError,
)

def main(req: func.HttpRequest) -> func.HttpResponse:
    request_id = get_request_id(req)

    try:
        body = validate_json_body(req)
        query = require_parameter(body, "query")
    except APIError as exc:
        return error_response(exc, request_id)

    # 処理...

    return json_response({"result": "success"})

ユーティリティ関数¶

`get_request_id(req)`¶

リクエストからトレーシングIDを取得または生成します。

request_id = get_request_id(req)
# => "abc123" or auto-generated UUID

`validate_json_body(req)`¶

リクエストボディをJSONとしてパースし、辞書であることを検証します。

try:
    body = validate_json_body(req)
except InvalidJSONError:
    # JSONパースエラー
except InvalidRequestError:
    # 辞書ではない

`require_parameter(body, name)`¶

必須パラメータを取得します。存在しないか空の場合は例外を発生させます。

try:
    query = require_parameter(body, "query")
except MissingParameterError:
    # パラメータが不足

`log_error(error, request_id, endpoint)`¶

構造化されたエラーログを出力します。

log_error(exc, request_id, "search", extra={"query": query})

ベストプラクティス¶

一貫したエラーコードを使用: 適切な ErrorCode を選択してください
詳細情報を含める: details パラメータで追加コンテキストを提供
リクエストIDを含める: すべてのエラーレスポンスに request_id を含める
適切なHTTPステータス: エラーの種類に応じた正しいステータスコードを使用
ログを残す: log_error() を使用して構造化ログを出力

対応エンドポイント¶

以下のエンドポイントが統一エラーハンドリングを使用しています：

/api/search - 検索API
/api/direct-answer - 直接回答API
/api/summarize - 要約API
/api/auth/* - 認証API
/api/reference - 参照API
/api/manage/* - 管理API

エラーハンドリング ガイド¶

概要¶