Une REST API bien conçue communique clairement le résultat d'une requête au moyen des codes de statut. Utilisez 200 OK pour une lecture réussie, 201 Created pour la création d'une ressource (la nouvelle URL dans l'en-tête Location) et 204 No Content pour une réussite sans corps à renvoyer (par exemple une suppression).
Les erreurs client se distinguent avec les 4xx. Le standard est 400 Bad Request pour une syntaxe incorrecte, 401 Unauthorized lorsqu'une authentification est requise, 403 Forbidden en l'absence de permission, 404 Not Found pour une ressource inexistante, 409 Conflict pour un conflit d'état, 422 Unprocessable Content pour un échec de validation et 429 Too Many Requests pour un excès de requêtes.
Les erreurs serveur se signalent avec les 5xx. Utilisez 500 Internal Server Error pour une exception inattendue et 503 Service Unavailable pour une surcharge ou une maintenance, en envoyant si possible l'en-tête Retry-After. Surtout, renvoyer toujours le même code de manière cohérente pour la même situation est ce qui détermine la facilité d'utilisation d'une API.