Manejo de errores

La API Annie Insights utiliza códigos de estado HTTP estándar y devuelve respuestas de error JSON estructuradas.

Formato de respuesta de error

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

Códigos de estado HTTP

Código	Estado	Descripción	Causa común
400	Solicitud incorrecta	Cuerpo de solicitud no válido o faltan parámetros requeridos	Faltan PatientID, TimeStamp o ImageName
401	No autorizado	Clave API no válida o faltante	Valor de encabezado incorrecto x-api-key
422	Entidad no procesable	La imagen no se pudo procesar	Imagen dañada, formato no compatible o contenido no dental
429	Demasiadas solicitudes	Límite de tarifa excedido	Demasiadas solicitudes en la ventana actual
500	Error Interno del Servidor	Fallo inesperado del servidor	Póngase en contacto con el soporte si persiste

Manejo de errores

401 - No autorizado

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

Solución: Verifique que su encabezado x-api-key esté presente y contenga una clave válida.

429 - Tarifa limitada

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

Solución: Implementar un retroceso exponencial. Verifique el encabezado Retry-After para conocer la duración de la espera.

422 — Entidad no procesable

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

Solución: Asegúrese de que la imagen sea una imagen dental JPEG/PNG válida con suficiente resolución.

Estrategia de reintento

Para errores transitorios (429, 500), implemente un retroceso exponencial:

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