Documentation

Erreurs, limites et quotas

Le format des erreurs, chaque code et quoi faire, les en-têtes RateLimit et les quotas de l’offre gratuite.

Le format des erreurs #

Toutes les erreurs de l’API ont la même forme, quel que soit leur statut :

JSON

{
  "error": {
    "code": "conversation_full",
    "message": "This conversation is full: start a new one."
  },
  "request_id": "req_3f9c…"
}

code est stable : c’est lui que votre code doit tester.
message est écrit pour les développeurs (en anglais) et peut changer.
request_id identifie la requête (aussi dans l’en-tête X-Request-Id) : citez-le au support.

Rien d’interne ne fuit (pas de trace, pas de message d’une couche inférieure), et une ressource qui n’existe pas répond comme une ressource qui appartient à quelqu’un d’autre : 404.

Tous les codes #

Statut	Code	Signification	Que faire
`401`	`unauthenticated`	Clé absente, inconnue, révoquée ou expirée	Vérifier la clé, en demander une nouvelle à l’équipe HubMix
`401`	`session_required`	Clé widget sans jeton visiteur	Ouvrir une session (`POST /sessions`)
`401`	`invalid_visitor_token`	Jeton visiteur expiré, effacé ou d’un autre client	Oublier le jeton, rouvrir une session
`403`	`origin_not_allowed`	Origine non déclarée pour ce client widget	Demander à l’équipe HubMix d’ajouter l’origine exacte
`403`	`consent_required`	L’avis en vigueur n’a pas été accepté (ou l’accord a été retiré)	Montrer l’avis, recueillir l’accord
`403`	`client_suspended`	Client suspendu	Contacter l’équipe HubMix
`403`	`insufficient_scope`	L’application n’a pas ce produit (route hors de ses scopes)	Demander à l’équipe HubMix d’ajouter le produit
`403`	`public_api_disabled`	L’API publique est désactivée sur ce serveur	Réessayer plus tard
`404`	`not_found`	Conversation ou message inconnu (ou d’un autre utilisateur)	Vérifier l’identifiant
`405`	`method_not_allowed`	Méthode HTTP non prise en charge	—
`409`	`conversation_full`	La conversation a atteint 60 messages	Commencer une nouvelle conversation
`413`	`payload_too_large`	Corps de plus de 32 Ko	Raccourcir la requête
`422`	`invalid_request`	Champ manquant ou invalide (le `message` liste les champs)	Corriger la requête
`422`	`invalid_end_user`	`X-End-User` mal formé	1 à 128 caractères ASCII imprimables
`422`	`notice_outdated`	Le consentement porte sur un ancien avis	Montrer le nouvel avis
`422`	`sessions_for_widgets_only`	`POST /sessions` avec une clé serveur	Utiliser `X-End-User` à la place
`422`	`not_an_answer`	Note sur un message qui n’est pas une réponse de Gaspard	Noter le `message_id` de la réponse
`429`	`rate_limited`	Quota de requêtes dépassé	Attendre `Retry-After` secondes
`429`	`token_quota_exceeded`	Quota mensuel de tokens atteint	Attendre le mois suivant (`Retry-After`) ou demander plus
`500`	`internal_error`	Erreur inattendue	Réessayer, citer `request_id`
`503`	`assistant_busy`	Gaspard est très sollicité	Réessayer après `Retry-After`
`503`	`assistant_unavailable`	Aucun modèle disponible pour l’instant	Réessayer plus tard

Les SDK ajoutent leurs propres codes, côté client : network_error, timeout, invalid_response et stream_incomplete (statut 0).

Quotas #

Chaque client a ses quotas, comptés par le service :

Fenêtre	Offre gratuite (défaut)	Erreur
Requêtes par minute, par client	10	`429 rate_limited`
Requêtes par minute, par visiteur (clé widget)	5	`429 rate_limited`
Requêtes par jour, par client	300	`429 rate_limited`
Tokens par mois, par client	200 000	`429 token_quota_exceeded`
Sessions visiteur par heure, par adresse IP	20	`429 rate_limited`

Ce sont les valeurs par défaut du service ; celles qui s’appliquent à votre application vous sont communiquées par l’équipe HubMix, qui la configure. Chaque client a au plus 3 clés actives. Les tokens comptent ce que le modèle lit et écrit pour répondre (question, contexte de connaissances, réponse), même si la connexion est coupée en cours de flux ; le jour est compté à l’heure suisse (Europe/Zurich).

Besoin de plus ? Les quotas d’un client peuvent être relevés par l’équipe HubMix (communes, écoles, institutions, partenaires) : contactez-nous.

Les en-têtes `RateLimit` #

Chaque réponse comptée annonce la fenêtre la plus proche de sa limite :

HTTP

RateLimit-Limit: 10
RateLimit-Remaining: 7
RateLimit-Reset: 42

RateLimit-Reset est en secondes. Au-delà de la limite, la réponse est 429 avec Retry-After (secondes). Ces en-têtes sont exposés aux navigateurs (CORS), comme X-Request-Id.

Réessayer correctement #

Réponse	Réessayer ?
`503 assistant_busy`, `429 rate_limited`	Oui, après `Retry-After` (sinon 0,5 s, 1 s, 2 s…)
Erreur réseau ou délai dépassé	Oui pour `GET` et `DELETE` ; pour une question, c’est sans risque aussi : un échange n’est enregistré qu’avec sa réponse
`429 token_quota_exceeded`	Non : le quota du mois est épuisé
Autres `4xx`	Non : corriger la requête
Un flux déjà commencé	Non : afficher l’erreur, laisser l’utilisateur relancer

Les SDK appliquent exactement ces règles (2 nouvelles tentatives par défaut, Retry-After plafonné à 30 s).

TypeScript

try {
  await gaspard.ask(id, question);
} catch (error) {
  if (error instanceof GaspardError) {
    if (error.code === 'conversation_full') id = (await gaspard.startConversation('fr')).id;
    else if (error.code === 'token_quota_exceeded') showQuotaMessage(error.retryAfter);
    else console.error(error.code, error.requestId);
  } else throw error;
}