Error codes

Cause : Invalid request body format (rare: the gateway prefers 422 for incorrect parameters).

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 : Check your key. Two headers are accepted: 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 : The account balance is not enough to cover the request's estimated cost.

Solution : Top up your account from the dashboard. You can also check your usage via GET /account/usage.

Cause : Forbidden host: raw IP call, wrong domain, or attempt to reach an internal route (e.g. GET /health) from the outside.

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

Solution : Always call the API via the public domain https://api-endpoints.alphaedge-ai.com.

Cause : Unknown model slug, unknown job identifier, or unrouted URL.

Messages typiques :

• {"detail": "Modèle introuvable."}
• {"detail": "Job de transcription introuvable."}
• {"detail": "Not Found"} (FastAPI fallback for unrouted URLs)

Solution : Check the model slug (catalog via GET /models) and the URL shape (method, path, path parameters).

Cause : The HTTP method is not supported on this route (e.g. GET on a POST-only endpoint).

Solution : Check the response header Allow which lists the methods accepted on the route.

Cause : The multipart contains unauthorized fields, the required file is missing or empty, or a boolean value is not in the accepted set.

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 : Adjust the form to match the returned message: exact field name (audio / image), boolean values among 1/0, true/false, yes/no, on/off.

Cause : Rare today (no application rate-limit on the gateway). May be returned by upstream network layers if a protection is enabled.

Solution : Honor the header Retry-After returned (5 s by default). Implement exponential backoff with jitter for retries.

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

Solution : Retry after a short wait. The JSON body includes a field request_id (identical to the header X-Request-ID) — share it with support to ease investigation.

Cause : The upstream service (ASR or OCR) returned an error the gateway can't map to an application code.

Solution : Retry; a header Retry-After (5 s) accompanies the response. If the problem persists, contact support with the X-Request-ID.

Cause : Startup in progress, overload or punctual maintenance.

Solution : Honor the header Retry-After (10 s by default). On traffic spikes, implement exponential backoff with jitter.

Cause : The gateway couldn't reach the key verification service or an upstream service in time.

Solution : Retry after Retry-After (5 s). If the problem persists, contact support with the X-Request-ID.