Log in Try the API

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": "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 : 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.