错误处理

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")