エラー処理

Annie Insights API は標準の HTTP ステータス コードを使用し、構造化された JSON エラー応答を返します。

エラー応答フォーマット

{
  "error": "Error Type",
  "message": "Human-readable description",
  "statusCode": 400
}

HTTPステータスコード

コード	状態	説明	よくある原因
400	要求の形式が正しくありません	リクエスト本文が無効か、必須パラメータが欠落しています	PatientID、TimeStamp、または ImageName がありません
401	無許可	API キーが無効または欠落しています	間違った x-api-key ヘッダー値
422	処理できないエンティティ	画像を処理できませんでした	破損した画像、サポートされていない形式、または歯科以外のコンテンツ
429	リクエストが多すぎます	レート制限を超えました	現在のウィンドウ内のリクエストが多すぎます
500	内部サーバーエラー	予期しないサーバー障害	解決しない場合はサポートにお問い合わせください

エラーの処理

401 — 不正

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "statusCode": 401
}

修正: x-api-key ヘッダーが存在し、有効なキーが含まれていることを確認してください。

429 — レート制限あり

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "statusCode": 429
}

修正: 指数バックオフを実装します。待機期間については、Retry-After ヘッダーを確認してください。

422 — 処理できないエンティティ

{
  "error": "Unprocessable Entity",
  "message": "The provided image could not be analyzed",
  "statusCode": 422
}

修正: 画像が十分な解像度を持つ有効な JPEG/PNG 歯科画像であることを確認してください。

再試行戦略

一時的なエラー (429、500) の場合は、指数バックオフを実装します。

import time
import requests

def call_api_with_retry(url, headers, body, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=body, headers=headers)
        if response.status_code == 200:
            return response.json()
        if response.status_code in [429, 500]:
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue
        response.raise_for_status()
    raise Exception("Max retries exceeded")