Comment lire une erreur liteserver

Un liteserver répond à chaque requête soit par l'objet demandé, soit par un liteServer.error portant un code entier et un message. La passerelle TONNode utilise la même enveloppe pour ses propres refus, si bien que votre bibliothèque les fait remonter comme n'importe quelle erreur de nœud : tonutils-go garde le code dans ton.LSError, pytoniq lève LiteServerError avec .code et .message, et ton-lite-client lève une Error dont le message est le texte seul.

Les codes viennent de deux endroits, et le tableau indique lequel :

  • Les codes de la passerelle — 400, 403, 429, 500, 502 — sont produits par la passerelle TONNode placée entre votre connexion ADNL et le nœud. Elle vérifie la méthode contre votre plan, applique la limite de débit et le plafond de concurrence, et route la requête vers un nœud léger ou un nœud d'archive. Ces lignes reprennent le chapitre 5 de la documentation LiteServers.
  • Les codes du nœud viennent du logiciel du nœud dans ton-blockchain/ton. -400 est le code par défaut avec lequel le texte d'un échec de LiteQuery est envoyé, -503 timeout est l'échéance par requête du nœud lui-même, et 651 et 652 sont ErrorCode::notready et ErrorCode::timeout de common/errorcode.h. Deux lignes sont émises par le client C++ lui-même (lite-client, tonlib) et non par le serveur ; les autres langages lèvent leurs propres exceptions dans ces situations.

Ceux qui comptent le plus

403 archive history is not included in this plan. Le seul signal qui compte quand vous parcourez l'historique. La requête avait besoin d'un bloc que le nœud léger ne conserve plus — le nœud léger garde environ deux jours d'historique au rythme actuel des blocs, un ordre de grandeur plutôt qu'une promesse — et le plan n'inclut pas l'archive. Inutile de réessayer : ajoutez l'archive au plan ou demandez un bloc plus récent. Le chapitre 4 explique où se trouve la frontière et contient une sonde qui la mesure pour votre clé.

429, trois limites différentes. too many requests est la limite de débit par clé, un leaky bucket libellé en unités de coût : une lecture ordinaire coûte 5, une page complète de getTransactions jusqu'à 16, un bloc entier 50. too many concurrent requests for this key est le plafond de requêtes en vol — la moitié du RPS du plan, avec un plancher de 8 et un plafond de 128. gateway is saturated est le plafond global de 256 requêtes en vol, tous clients confondus. Les deux premiers signifient que votre client doit se cadencer ; le dernier, que le backend peine, et la bonne réponse est le backoff. Le chapitre 7 contient la table des coûts et des extraits de client cadencé.

502 backend node timeout. Le nœud n'a pas répondu dans la fenêtre de la passerelle : 7 s pour le nœud léger, 20 s pour l'archive. Réglez votre propre timeout client au-dessus de ces valeurs ; un timeout plus court transforme un vrai 502 en timeout local et perd le diagnostic.

651 et la famille « not in db ». block … is not applied, block … is not in db et lt not in db portent tous ErrorCode::notready. Ils signifient que ce nœud n'a pas prêt ce que vous avez demandé : il est encore en train de rattraper son retard, le bloc est en avance sur son état, ou le bloc ou le temps logique est plus ancien que son stockage. Un bloc récent apparaîtra de lui-même ; un bloc ancien demande l'archive.

Que réessayer

Réessayez 429 avec un backoff et 502 une fois, immédiatement. Ne réessayez pas 403 — aucune variante ne devient vraie à la deuxième tentative. Ne réessayez pas non plus -400 issu d'un parcours de transactions ; c'est une frontière, pas un incident. Pour 651, réessayez après un instant un bloc plus récent que l'état du nœud, et cessez de réessayer un bloc plus ancien que son stockage.

Erreurs du flux mempool

Le flux mempool est un protocole différent avec sa propre liste d'erreurs — des messages JSON error et des codes de fermeture WebSocket comme 4401 et 4429 — et n'est pas couvert par ce tableau.