# « 431 Request Header Fields Too Large » sur une API REST : un jeton trop lourd

> Ce statut HTTP rarement rencontré signale presque toujours un en-tête d'autorisation qui a grossi avec le temps, jusqu'à dépasser la limite du serveur web.

- Auteur : WordPress Développement
- Publié le : 2022-04-12
- Mis à jour le : 2022-04-12
- Catégorie : Headless & API
- URL : https://www.wpmoderne.fr/headless/431-request-header-fields-too-large-jeton-lourd/

## L’essentiel

- Le statut 431 concerne la taille des en-têtes, pas celle du corps de requête
- Un jeton d'application peut grossir s'il encode trop d'informations
- Une limite serveur mal dimensionnée aggrave le symptôme sans en être la cause

`431 Request Header Fields Too Large` : ce statut, défini par la RFC 6585, ne fait pas partie des erreurs qu'un développeur WordPress croise souvent. Il ne concerne ni le corps de la requête, ni les données envoyées en JSON, ni même la logique métier d'une route REST personnalisée. Il signale une seule chose : la totalité des en-têtes HTTP envoyés dépasse la limite acceptée par le serveur web ou le serveur d'application qui reçoit la requête, avant même que WordPress n'ait la moindre chance de la traiter.

## Symptôme

Une intégration front consomme normalement une route REST authentifiée par mot de passe d'application, transmis dans l'en-tête `Authorization`. Après plusieurs semaines de fonctionnement sans incident, certaines requêtes commencent à échouer avec un statut 431, de façon intermittente puis de plus en plus fréquente, sans qu'aucun changement n'ait été apporté au code de l'intégration elle-même.

## Diagnostic

La cause la plus fréquente de ce statut, en dehors d'une attaque volontaire par en-têtes gonflés, tient à un en-tête d'autorisation qui grossit progressivement. C'est particulièrement le cas quand le jeton transmis n'est pas un simple mot de passe d'application (qui reste toujours de longueur fixe et raisonnable), mais un jeton composite construit par une couche intermédiaire — par exemple un jeton qui encode, en plus de l'identifiant utilisateur, l'historique de ses permissions ou une liste de scopes qui s'allonge avec le temps.

Un serveur Nginx configuré avec sa limite par défaut accepte généralement jusqu'à 8 kilo-octets pour l'ensemble des en-têtes d'une requête. Un jeton qui grossit de quelques centaines d'octets par mois, additionné aux autres en-têtes habituels (cookies de session, en-têtes de proxy, informations de user-agent), finit par franchir ce seuil, provoquant l'échec systématique de toute requête pour l'utilisateur concerné, jusqu'à ce que son jeton soit régénéré ou que la limite serveur soit augmentée.

> L'essentiel à retenir : Le statut 431 concerne la taille des en-têtes, pas celle du corps de requête ; Un jeton d'application peut grossir s'il encode trop d'informations ; Une limite serveur mal dimensionnée aggrave le symptôme sans en être la cause

## Correctif

Deux niveaux d'intervention s'imposent, l'un pour traiter le symptôme immédiat, l'autre pour traiter la cause :

```
# nginx.conf, dans le bloc http ou server concerné
large_client_header_buffers 4 16k;
```

Cette directive augmente la limite acceptée pour les en-têtes, ce qui débloque immédiatement les utilisateurs affectés. Elle ne règle cependant rien sur le fond : si le jeton continue de grossir sans limite, le nouveau seuil finira lui aussi par être atteint. Le correctif réel consiste à revoir la structure du jeton pour qu'il reste de taille bornée, quelle que soit l'ancienneté du compte ou le nombre de permissions accumulées — en stockant par exemple les scopes détaillés côté serveur, associés à un identifiant court transmis dans l'en-tête, plutôt que d'encoder l'ensemble des informations directement dans le jeton lui-même.

## Prévention

- Surveiller périodiquement la taille moyenne des jetons d'autorisation en circulation, pas seulement leur validité
- Préférer un identifiant de session court, résolu côté serveur, à un jeton qui embarque directement toutes les informations utiles
- Documenter la limite d'en-têtes réellement configurée sur l'infrastructure de production, pour éviter de la découvrir uniquement lors d'un incident

## Ce que ce statut ne signifie pas

Il est tentant, en voyant ce statut pour la première fois, de chercher le problème du côté de WordPress lui-même, ou du contrôleur REST concerné. Ce serait une erreur d'aiguillage : la requête n'atteint jamais PHP dans ce cas de figure, elle est rejetée en amont par le serveur web avant même que WordPress ne soit sollicité. Aucun message d'erreur applicatif, aucune trace dans les journaux de WordPress n'apparaîtra donc pour ce type d'incident ; seuls les journaux du serveur web (Nginx ou Apache) porteront la trace du rejet.

## En résumé

Le statut 431 reste rare, mais son diagnostic est presque toujours le même une fois qu'on sait où chercher : un en-tête, le plus souvent celui d'autorisation, a fini par dépasser la limite acceptée par le serveur web. Augmenter cette limite traite l'urgence ; revoir la structure du jeton pour qu'il reste borné en taille traite le problème à sa racine.