Section 09 sur 12

Erreurs

Chaque erreur est {"error": {"code", "reason", "message", "details"?}} avec le vrai statut HTTP. reason est le slug stable sur lequel brancher votre code ; code (de la forme QVST1-3404) est la référence à citer au support ; message est un texte en anglais pour les humains, susceptible de changer. Les erreurs ne coûtent aucune unité ; seules les réponses 429 et 402 sont comptées dans les chiffres d'erreurs par clé de la page de compte.

Erreurs Quavsit#

Statut	reason	code	Quand
400	`invalid_location`	`QVST1-1400`	`near`, `bbox` ou `radius` mal formé
400	`transit_query_invalid`	`QVST1-2400`	valeur ou combinaison de paramètres invalide ; `details.reason = "cross_network"` sur les itinéraires
404	`place_not_found`	`QVST1-4404`	`from` ou `to` n'a pas pu être résolu
404	`network_not_found`	`QVST1-1404`	slug de réseau inconnu
404	`line_not_found`	`QVST1-2404`	identifiant de ligne inconnu
404	`stop_not_found`	`QVST1-3404`	identifiant d'arrêt ou de zone inconnu
404	`capability_unsupported`	`QVST1-5404`	le réseau n'a pas cette donnée (véhicules, calculateur natif)
409	`key_limit_reached`	`QVST1-1409`	nombre maximal de clés du plan atteint (API de compte)
429	`stream_limit_reached`	`QVST1-1429`	trop de streams simultanés
429	`spend_cap_reached`	`QVST1-2429`	plafond de dépense mensuel atteint en dépassement ; `details {spend_cap_cents, spent_cents, period}`
502	`transit_upstream_error`	`QVST9-1502`	le flux opérateur a échoué et aucune copie en cache n'est utilisable
503	`transit_upstream_budget`	`QVST9-3503`	quota quotidien amont épuisé et aucune copie en cache
503	`network_data_unavailable`	`QVST9-4503`	données théoriques pas encore importées pour ce réseau
503	`quavsit_unconfigured`	`QVST2-1503`	configuration manquante de notre côté
504	`transit_upstream_timeout`	`QVST9-2504`	le flux opérateur n'a pas répondu à temps

place_not_found est un 404 : l'endroit demandé n'a pas pu être résolu ; c'est reason qui sert au branchement.

Erreurs de la plateforme#

La couche d'identité et de comptage répond avec ses propres préfixes ; voici celles qu'un client de l'API rencontre.

Statut	reason	code	Quand
401	`authentication_required`	`SCTY3-1401`	pas de clé Bearer
401	`invalid_token`	`SCTY3-2401`	token inconnu, révoqué ou qui n'est pas une clé d'API
402	`plan_required`	`MARL1-1402`	streams sur un plan qui ne les inclut pas, ou dépassement sur un plan sans dépassement
403	`insufficient_scope`	`SCTY3-2403`	mauvaise audience ou mauvais scope, ou clé non personnelle
403	`email_verification_required`	`MAIL3-1403`	e-mail du compte non vérifié
404	`not_found`	`APIE1-0404`	route inconnue
429	`rate_limited`	`APIE1-0429`	limite par minute dépassée ; réessayez après l'en-tête `Retry-After`
429	`quota_exhausted`	`APIE1-1429`	unités mensuelles épuisées ; `details {plan, period, limit, used, remaining, resets_at, overage_available, upgrade_url}`
500	`internal_error`	`APIE2-1500`	défaillance inattendue de notre côté

Conseils de traitement#

Branchez sur reason, jamais sur message.
Sur rate_limited, attendez le nombre de secondes de Retry-After ; sur quota_exhausted, lisez details.resets_at et, si details.overage_available est vrai, envisagez d'activer le dépassement sur la page de compte.
Sur transit_upstream_*, réessayez une fois après quelques secondes ; la réponse peut revenir stale (voir la fraîcheur) plutôt qu'échouer.
Conservez le code dans vos journaux ; c'est ce que le support demande.

json

{"error": {"code": "APIE1-1429", "reason": "quota_exhausted", "message": "Monthly units exhausted.",
  "details": {"plan": "free", "period": "2026-09", "limit": 5000, "used": 5000, "remaining": 0,
    "resets_at": "2026-10-01T00:00:00Z", "overage_available": false, "upgrade_url": "https://my.quavern.com/account/quavsit"}}}