Error codes

Quickly identify and resolve your technical incidents. This section lists the AlphaEdge API error codes, their causes and the corresponding fixes.

Headers useful for all errors

X-Request-ID — unique identifier present on every response (auto-generated or an echo of the value sent by the client). Provide it to support to ease server-side correlation. On a 500 error, the identifier is also duplicated in the JSON body: {"detail": "...", "request_id": "..."}.
Retry-After — present on 429, 502, 503 and 504 responses. Gives the recommended wait time (in seconds) before a retry. Respect this value on the client side (backoff).

Error messages emitted by the gateway are in French. A few default 404 / 405 messages ("Not Found", "Method Not Allowed") remain in English — this is the standard FastAPI fallback.

List of error codes

400

Malformed request

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

Solution : Make sure the body matches the declared content-type. For multipart requests, let the client (curl -F, requests, fetch+FormData) generate the boundary.

401

Authentication failed

Cause : API key missing, empty or invalid.

Typical message : {"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. If you don't have one, create a key on your dashboard.

402

Insufficient balance

Cause : The account balance is not enough to cover the estimated cost of the request.

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

403

Access forbidden

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

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

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

404

Resource not found

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

Typical messages :

{"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 form (method, path, path parameters).

405

Method not allowed

Cause : The HTTP method used 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 for the route.

422

Invalid parameters

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

Example messages :

{"detail": "Formulaire multipart invalide : champ autorisé = `audio` (fichier requis). Tout autre champ est refusé."}
{"detail": "Fichier audio illisible ou format non reconnu."}

Solution : Adapt the form according to the returned message: exact field name (audio / image), boolean values among 1/0, true/false, yes/no, on/off.

429

Too many requests

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

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

500

Internal server error

Cause : The server encountered an uncaught problem.

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

502

Downstream service error

Cause : The upstream service (ASR or OCR) returned an error that the gateway cannot translate into an application code.

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

503

Service unavailable

Cause : Starting up, overload or occasional maintenance.

Solution : Respect the header Retry-After (10 s by default). In case of a traffic spike, implement exponential backoff with jitter.

504

Upstream timeout

Cause : The gateway could not reach the key verification service or an upstream service in time.

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

Best practices

To avoid errors and improve your application's robustness:

Error handling : Capture all 4xx and 5xx codes and inspect the field detail of the JSON body for an explicit message (in French).
Retry logic : On 429 / 502 / 503 / 504, respect the header Retry-After. Otherwise, use exponential backoff with jitter.
Validation : Validate your parameters before sending to avoid 422 errors.
Traceability : Keep the header X-Request-ID returned by each response. To pre-generate a client identifier, send your own X-Request-ID upstream: it will be reused as-is in the response.
Monitoring : Monitor your balance regularly via GET /account/me to avoid 402 errors.