201 Created : confirmer la création d’une nouvelle ressource

201 Created confirme qu’une requête a réussi et créé quelque chose de nouveau : un compte, une commande, un fichier envoyé, un enregistrement dans une API. C’est un statut pour les opérations d’écriture, et la réponse doit pointer vers la nouvelle ressource.

Définition

La RFC 9110, section 15.3.2 précise que la requête « a été satisfaite et a abouti à la création d’une ou plusieurs nouvelles ressources ». La principale nouvelle ressource est identifiée par l’en-tête Location ou, à défaut, par l’URL de la requête. Le corps décrit en général la nouvelle ressource et renvoie vers elle. Un 201 répond le plus souvent à un POST (création dans une collection) ou à un PUT (création à une URL choisie par le client).

POST /api/v1/articles HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"title":"HTTP status codes for SEO"}

HTTP/1.1 201 Created
Location: /api/v1/articles/4821
Content-Type: application/json

{"id":4821,"title":"HTTP status codes for SEO","status":"draft"}

Si le travail n’est pas encore terminé, 202 Accepted est plus honnête. Si la ressource existe déjà, envisagez 409 Conflict ; si les données échouent à la validation, 422 Unprocessable Content.

Impact SEO

Les pages destinées à la recherche doivent répondre à un GET par 200 OK, pas par 201. La documentation de Google indique que pour 201 et 202, Googlebot attend le contenu pendant un temps limité, puis transmet ce qu’il a reçu au processus d’indexation. Une page servie en 201 peut donc être traitée, mais ce statut révèle une erreur de routage ou de code, par exemple un contrôleur écrit pour créer des enregistrements et réutilisé pour afficher une page publique. Corrigez-la plutôt que de compter sur la tolérance de Google.

Conseils pour les développeurs

• Envoyez toujours Location avec l’URL de la nouvelle ressource.
• Renvoyez la représentation créée dans le corps pour épargner une seconde requête au client.
• Rendez les points d’accès de création sûrs en cas de nouvelle tentative, par exemple avec une clé d’idempotence, afin qu’une requête répétée ne crée pas de doublons.

Comment vérifier

Passez vos URL publiques dans le vérificateur de statut HTTP ; tout autre code que 200 sur une page indexable mérite un examen. Pour les points d’accès d’API, curl avec -i affiche la ligne de statut et l’en-tête Location :

curl -i -X POST https://api.example.com/v1/articles \
  -H 'Content-Type: application/json' -d '{"title":"Draft"}'

Questions fréquentes