Error codes

Cause : Format du corps de requête invalide (rare : la passerelle privilégie la 422 pour les paramètres incorrects).

Solution : Vérifiez que le corps respecte le content-type annoncé. Pour les requêtes multipart, laissez le client (curl -F, requests, fetch+FormData) générer le boundary.

Cause : Clé API absente, vide ou invalide.

Message typique : {"detail": "Clé API manquante : fournissez l’en-tête X-API-Key ou Authorization: Bearer <clé>."}

Solution : Vérifiez votre clé. Deux en-têtes sont acceptés : X-API-Key: TA_CLE or Authorization: Bearer TA_CLE. Si vous n'en avez pas, créez une clé sur votre tableau de bord.

Cause : Le solde du compte ne permet pas de couvrir le coût estimé de la requête.

Solution : Rechargez votre compte depuis le tableau de bord. Vous pouvez aussi consulter votre consommation via GET /account/usage.

Cause : Hôte non autorisé : appel par IP brute, mauvais domaine, ou tentative d'accès à une route interne (ex. GET /health) depuis l'extérieur.

Message typique : {"detail": "Utiliser le nom de domaine « api-endpoints.alphaedge-ai.com » dans l’URL…"}

Solution : Toujours appeler l'API via le nom de domaine public https://api-endpoints.alphaedge-ai.com.

Cause : Slug de modèle inexistant, identifiant de job inconnu, ou URL non routée.

Messages typiques :

• {"detail": "Modèle introuvable."}
• {"detail": "Job de transcription introuvable."}
• {"detail": "Not Found"} (fallback FastAPI pour les URL non routées)

Solution : Vérifiez le slug du modèle (catalogue via GET /models) et la forme de l'URL (méthode, path, paramètres de chemin).

Cause : La méthode HTTP utilisée n'est pas supportée sur cette route (ex. GET sur un endpoint POST-only).

Solution : Consultez l'en-tête de réponse Allow qui liste les méthodes acceptées pour la route.

Cause : Le multipart contient des champs non autorisés, le fichier requis est absent ou vide, ou une valeur booléenne ne fait pas partie des valeurs acceptées.

Exemples de messages :

• {"detail": "Champ booléen invalide pour `enable_diarization`: 'banane'. Valeurs acceptées : 1/0, true/false, yes/no, on/off."}
• {"detail": "Formulaire multipart invalide : champs autorisés = `audio` (fichier requis), `enable_diarization`, `enable_postcorrect`. Tout autre champ est refusé."}
• {"detail": "Fichier audio illisible ou format non reconnu."}

Solution : Adaptez le formulaire selon le message renvoyé : nom de champ exact (audio / image), valeurs booléennes parmi 1/0, true/false, yes/no, on/off.

Cause : Cas rare aujourd'hui (aucun rate-limit applicatif côté gateway). Peut être renvoyé par les couches réseau en amont si une protection est activée.

Solution : Respectez l'en-tête Retry-After renvoyé (5 s par défaut). Implémentez un backoff exponentiel avec jitter pour les retries.

Cause : Le serveur rencontre un problème non rattrapé.

Solution : Réessayez après une brève attente. Le corps JSON inclut un champ request_id (identique au header X-Request-ID) — transmettez-le au support pour faciliter l'investigation.

Cause : Le service amont (ASR ou OCR) a renvoyé une erreur que la passerelle ne peut pas traduire en code applicatif.

Solution : Réessayez ; un en-tête Retry-After (5 s) accompagne la réponse. Si le problème persiste, contactez le support avec le X-Request-ID.

Cause : Démarrage en cours, surcharge ou maintenance ponctuelle.

Solution : Respectez l'en-tête Retry-After (10 s par défaut). En cas de pic de trafic, implémentez un backoff exponentiel avec jitter.

Cause : La passerelle n'a pas pu joindre le service de vérification de clé ou un service amont à temps.

Solution : Réessayez après Retry-After (5 s). Si le problème persiste, contactez le support avec le X-Request-ID.