Un parseur qui affiche “invalid JSON” ne donne que le symptôme. La cause peut être une virgule finale, une chaîne mal échappée, un HTML de login renvoyé par un proxy, un corps tronqué, un charset incohérent ou une valeur qui respecte la syntaxe mais pas le schéma. Déboguer correctement demande de regarder le texte, les octets, les en-têtes et le contrat attendu.

Commencez par capturer ce qui est vraiment arrivé

Avant de modifier le producteur, conservez le corps exact de la requête ou de la réponse. Vérifiez le status code, le content type, la compression, la longueur reçue et le premier caractère. Beaucoup de clients attendent JSON mais reçoivent une page HTML d’erreur, une redirection ou un message texte.

Si le serveur a renvoyé une page de maintenance, chercher une virgule manquante dans le payload est une perte de temps. Le problème se situe dans le transport ou le routage.

Les chaînes sont une source fréquente d’erreurs

JSON exige des guillemets doubles pour les chaînes et des échappements précis. Un saut de ligne réel dans une chaîne, un backslash incomplet ou une guillemet non échappée casse le document. Ces bugs apparaissent souvent lorsque le JSON est construit par concaténation.

La solution durable est d’utiliser un sérialiseur. Il connaît les règles d’échappement et évite que les données utilisateur deviennent de la syntaxe.

Encoding et caractères invisibles comptent

Un document visuellement correct peut contenir un byte order mark inattendu, un caractère de contrôle ou des octets encodés autrement que prévu. Les éditeurs et tableurs introduisent parfois des caractères invisibles. Dans ces cas, regarder les octets avec un outil adapté est plus utile que reformater le texte.

Le contrat devrait préciser UTF-8 et le serveur devrait envoyer des en-têtes cohérents. Les parsers tolérants peuvent masquer le problème jusqu’à ce qu’un autre langage le refuse.

JSON strict n’accepte pas tout JavaScript

Les commentaires, trailing commas et quotes simples peuvent fonctionner dans un fichier JavaScript ou un parseur permissif. Ils ne font pas partie de JSON strict. Un fichier qui passe localement peut donc échouer dans une bibliothèque de production plus stricte.

Pour de la configuration humaine, choisissez éventuellement un format qui autorise ces éléments. Pour un contrat entre systèmes, rester strict évite des extensions implicites.

Un document valide peut perdre des données

Le parseur peut accepter un nombre immense, puis le langage le stocke avec une précision insuffisante. Un identifiant se trouve alors arrondi. Une valeur financière en floating point peut changer légèrement. Le JSON était syntaxiquement valide; le bug est une erreur de type.

Comparez le texte original et le modèle désérialisé. Si la valeur change après parsing, il faut modifier le contrat, souvent en utilisant une chaîne pour les identifiants et montants exacts.

Les réponses tronquées trompent le diagnostic

Un timeout, une limite de proxy ou une connexion interrompue peut produire un JSON presque complet. Le parseur se plaint d’un tableau non fermé ou d’une chaîne inachevée. La vraie cause se trouve dans la taille, le buffering ou l’infrastructure.

Mesurer longueur attendue, longueur reçue et identifiant de requête aide à repérer ces situations. Si seuls les gros payloads échouent, vérifiez les limites avant de réécrire le serializer.

Séparez syntaxe et validation métier

Un JSON peut être parfaitement parseable et tout de même incorrect: champ requis absent, type inattendu, enum inconnu, date sans fuseau. Ces erreurs doivent produire une validation claire, pas le même message que du JSON mal formé.

Cette séparation aide les clients. Ils savent s’ils doivent réparer l’encodage, la syntaxe ou le contenu de domaine.

Rendez le cas reproductible

Réduisez le payload en conservant le même encodage et les mêmes en-têtes pertinents. Ne laissez pas un formatter réparer automatiquement le document avant d’avoir compris. Si le bug dépend du transport, gardez aussi les tailles et les headers.

Le cas minimal doit rejoindre les tests. Un fixture réel empêche le bug de revenir lors d’une mise à jour de bibliothèque, d’un changement de framework ou d’une migration d’infrastructure.

Prévenir vaut mieux que deviner

Utilisez des sérialiseurs maintenus, des content types explicites, des limites de taille, des schémas et des logs qui distinguent les catégories d’erreurs. Évitez de construire JSON à la main et d’accepter des extensions non documentées.

Les outils doivent préserver le payload original

Un formatter peut rendre un document plus lisible, mais il peut aussi supprimer l’indice du problème: whitespace, ordre, BOM, caractère de contrôle ou encodage. Pour un incident réel, conservez toujours une copie brute avant de reformater. Cette copie est la preuve qui permettra de comparer les couches.

Les équipes gagnent du temps lorsqu’elles savent quelle version du payload a été vue par le client, le proxy et le serveur applicatif.

Le débogage devient beaucoup plus court lorsque le système traite JSON comme un contrat complet: octets attendus, syntaxe stricte, encodage clair et signification validée par tests.