Une route REST retourne 400 sur un paramètre manquant, sans préciser lequel

Douze paramètres possibles, une réponse 400, et un message qui se contente de dire "Invalid parameter(s)" sans jamais nommer le coupable : ce scénario revient régulièrement sur des routes REST personnalisées un peu chargées, et il transforme un simple oubli de champ en séance de devinettes côté équipe front.

Symptôme

Le front headless envoie une requête POST vers une route personnalisée avec un formulaire de plusieurs champs. La réponse arrive avec un statut 400 et un corps qui ressemble à ceci : {"code":"rest_missing_callback_param","message":"Missing parameter(s): "}, parfois même avec la liste des paramètres tronquée ou vide selon la façon dont l’erreur a été construite côté serveur. Le développeur front ouvre les outils réseau du navigateur, relit la charge envoyée, et ne voit rien d’anormal à l’œil nu parmi une dizaine de champs.

Diagnostic

Le format d’erreur natif de WordPress, quand un argument required est absent, est en réalité bien plus précis que ce que beaucoup de fronts affichent. L’objet WP_Error renvoyé par le contrôleur contient une donnée structurée, accessible sous la clé data, elle-même contenant params : un tableau listant précisément les noms des paramètres jugés manquants ou invalides. Le problème ne vient donc généralement pas de WordPress, mais de la façon dont la réponse d’erreur est consommée côté client, ou dont elle a été reconstruite manuellement côté serveur dans une route personnalisée qui n’utilise pas le mécanisme natif de validation des arguments.

Sur une route bâtie à la main sans passer par le tableau args de register_rest_route(), un développeur qui construit lui-même son WP_Error pour signaler un champ manquant oublie souvent de renseigner cette clé data.params, se contentant d’un message textuel générique. Résultat : l’information existe quelque part dans la logique de validation, mais jamais dans la réponse envoyée au client.

Correctif

function verifier_arguments( $request ) {
    $obligatoires = array( 'email', 'nom', 'consentement' );
    $manquants    = array();

    foreach ( $obligatoires as $champ ) {
        if ( null === $request->get_param( $champ ) ) {
            $manquants[] = $champ;
        }
    }

    if ( ! empty( $manquants ) ) {
        return new WP_Error(
            'champs_manquants',
            sprintf( 'Paramètre(s) manquant(s) : %s', implode( ', ', $manquants ) ),
            array(
                'status' => 400,
                'params' => $manquants,
            )
        );
    }

    return true;
}

La clé status à l’intérieur du tableau data garantit que WordPress renvoie bien le code HTTP 400 attendu, tandis que params restitue la liste exacte des champs concernés dans un format que le front peut exploiter sans avoir à analyser un message textuel. Côté client, il devient alors possible d’afficher, à côté de chaque champ de formulaire fautif, une indication précise plutôt qu’un message global peu utile.

Pour les routes qui s’appuient déjà sur le tableau args natif de register_rest_route(), le comportement est identique dès lors que chaque argument est correctement déclaré avec required : WordPress construit automatiquement l’objet WP_Error avec la clé params renseignée, sans code supplémentaire à écrire.

Prévention

• Préférer le tableau args natif de register_rest_route() plutôt qu’une validation manuelle dans le callback, chaque fois que c’est possible
• Quand une validation manuelle reste nécessaire, toujours renseigner data.params dans le WP_Error retourné
• Côté front, journaliser systématiquement le corps complet de la réponse d’erreur en environnement de développement, pas seulement le message

Pour aller plus loin

Ce type de désagrément illustre une règle plus générale sur l’API REST de WordPress : la structure d’erreur est riche, mais rien n’oblige un développeur à l’exploiter pleinement. Un WP_Error minimal, réduit à un message textuel, reste valide et fonctionnera, mais prive le client de toute possibilité de réagir de façon fine. Sur un projet headless où le front doit guider l’utilisateur champ par champ, s’assurer que chaque erreur de validation transporte sa liste de paramètres fautifs évite bien des allers-retours entre équipes pour comprendre ce qui, au fond, n’était qu’un détail de sérialisation d’erreur.