Tratamento de erros

A API Annie Insights usa códigos de status HTTP padrão e retorna respostas de erro JSON estruturadas.

Formato de resposta de erro

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

Códigos de status HTTP

Código	Status	Descrição	Causa Comum
400	Pedido ruim	Corpo da solicitação inválido ou parâmetros obrigatórios ausentes	PatientID, TimeStamp ou ImageName ausentes
401	Não autorizado	Chave de API inválida ou ausente	Valor do cabeçalho x-api-key incorreto
422	Entidade não processável	Não foi possível processar a imagem	Imagem corrompida, formato incompatível ou conteúdo não odontológico
429	Muitas solicitações	Limite de taxa excedido	Muitas solicitações na janela atual
500	Erro do Servidor Interno	Falha inesperada do servidor	Entre em contato com o suporte se persistir

Tratamento de erros

401 – Não autorizado

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

Correção: Verifique se seu cabeçalho x-api-key está presente e contém uma chave válida.

429 – Taxa Limitada

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

Correção: Implemente a espera exponencial. Verifique o cabeçalho Retry-After para saber a duração da espera.

422 – Entidade Não Processável

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

Correção: Certifique-se de que a imagem seja uma imagem dentária JPEG/PNG válida com resolução suficiente.

Estratégia de nova tentativa

Para erros transitórios (429, 500), implemente a espera 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")