3GK AI3GK AIDocumentation
API publiqueCodes d'erreur

Codes d'erreur

Toutes les erreurs sont renvoyées au format OpenAI{ error: { message, type, code } } avec un code HTTP cohérent. Les SDK officiels parsent ce format nativement et lèvent des exceptions typées.

Format d'erreur#format

Tous les status >= 400 renvoient un body JSON de la forme suivante. Le champ code identifie la cause de manière stable, le message est destiné aux humains.

application/json
{
  "error": {
    "message": "Modèle \"foo\" inconnu. Modèles disponibles : \"3gk-llm\" (Chat completions), \"3gk-embed\" (Embeddings), \"3gk-rerank\" (Reranking).",
    "type": "model_not_supported",
    "code": "model_not_supported"
  }
}

Codes & causes#codes

400
invalid_request · Body absent, JSON invalide, ou champ obligatoire manquant (model, messages).
400
model_not_supported · L'identifiant demandé n'est pas dans la liste exposée par GET /v1/models (alias 3gk-*).
401
auth_error · Header Authorization manquant, mal formé, clé révoquée ou compte client suspendu.
500
internal · Erreur native côté gateway (cas exceptionnel). Le id de la réponse, s'il est renvoyé, permet à l'admin de retrouver la trace.
502
upstream_error · Le backend choisi (primaire ou secours) a renvoyé un 5xx, un JSON invalide ou s'est avéré injoignable au niveau réseau.
503
upstream_error · Aucun backend disponible pour servir le modèle demandé (configuration en cours côté plateforme).
504
upstream_timeout · Le backend a dépassé le timeout configuré (par défaut 600 s ; surchargeable par instance).

Stratégies de retry#strategies

  • 400 / 401 — ne pas retry. Corriger le payload ou la clé.
  • 500 / 502 — retry avec backoff exponentiel (jusqu'à 3 tentatives, 1 s · 4 s · 16 s).
  • 503 — l'incident est administratif (modèle par défaut absent ou fallback non configuré). Avertir l'utilisateur final, ne pas hammerer.
  • 504 — réduire max_tokens ou simplifier le prompt. Le timeout par défaut est large (600 s).
Pas de quotas exposés en V1. La gateway ne renvoie pas d'erreur 429 rate_limit_exceeded ni de headers X-RateLimit-* en V1 — le contrôle de débit est assuré par l'infrastructure réseau. Ne codez pas de gestion 429 spécifique pour le moment.