Erreurs

Tous les corps d'erreur ressemblent à ceci :

json
{
  "type": "https://api.alloovium.com/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "API key is missing required scope: vault:write",
  "instance": "/api/v2/vault/projects",
  "code": "insufficient_scope",
  "request_id": "req_01HQZ4R9VYTC5H6NPRDFG8EJUS"
}

Chaque réponse — erreur ou succès — porte un header header. Sur les 5xx, le même ID est également intégré dans le corps. Incluez-le lorsque vous contactez le support :

text
X-Request-Id: req_01HQZ4R9VYTC5H6NPRDFG8EJUS

Le support peut tracer la requête à travers chaque couche — load balancer, handler FastAPI, requêtes base de données, appels LLM en aval — en utilisant uniquement cet ID.

Lorsque le validateur Pydantic de FastAPI rejette un corps de requête avant qu'il n'atteigne un handler, la même enveloppe porte une liste field mappant vers les chemins de champs en échec :

json
{
  "type": "https://api.alloovium.com/errors/validation_error",
  "title": "Request validation failed",
  "status": 422,
  "detail": "1 field failed validation",
  "code": "validation_error",
  "field_errors": [
    {"loc": ["body", "name"], "msg": "Field required", "type": "missing"}
  ]
}

python
import httpx

class AllooviumError(Exception):
    def __init__(self, payload):
        self.code = payload.get("code")
        self.status = payload.get("status")
        self.detail = payload.get("detail")
        self.request_id = payload.get("request_id")
        super().__init__(f"{self.code}: {self.detail}")

def raise_for_problem(resp: httpx.Response):
    if resp.is_success:
        return
    try:
        payload = resp.json()
    except Exception:
        resp.raise_for_status()
        return
    raise AllooviumError(payload)

try:
    resp = httpx.get(url, headers=headers)
    raise_for_problem(resp)
except AllooviumError as e:
    if e.code == "insufficient_scope":
        prompt_user_to_grant_scope()
    elif e.code == "rate_limited":
        sleep_and_retry()
    else:
        log.error("Alloovium call failed", code=e.code, request_id=e.request_id)
        raise

• Limites de débit — stratégie de retry complète pour 429 et 5xx.
• Idempotence — comment éviter que les retries créent des doublons.