Meilleures pratiques de gestion des erreurs des API REST : Codes d'état, RFC 9457 et erreurs réessayables

Designing a robust error contract for a REST API is crucial, as error responses form an integral part of the contract. Clients analyze these errors, retry mechanisms rely on them, and support teams consult them during late-night hours. However, many teams document the normal path while leaving errors to default framework values. As a result, an API may contain multiple error formats, a 200 response with success: false, or even a stack trace revealing the database schema.

This guide presents a comprehensive approach from start to finish, covering the selection of the appropriate HTTP code, standardizing the error body using Problem Details from RFC 9457, separating machine codes from human messages, indicating whether an error is retryable, and preventing any sensitive information leakage. It also demonstrates how to test each failure path in Apidog.

Start with the HTTP status code, not the HTTP body. The body already provides a first layer of semantics. RFC 9110 defines families of HTTP status codes, such as 4xx (client errors), which will generally fail again with the same request, and 5xx (server or dependency errors), where the client's request may be valid. Generic clients, proxies, caches, and retry libraries use these codes without reading your JSON. Consult the MDN reference for HTTP status codes and apply a consistent convention.

Use the correct code for the situation. Do not use it incorrectly, as it can reveal sensitive information. For example, use 400 Bad Request for invalid JSON, incorrect content type, or missing required fields, and 422 Unprocessable Content when the request is valid but business rules are violated, such as negative amounts or unsupported currencies.

Use 401 Unauthorized when the client has not proven its identity, and 403 Forbidden when the identity is known but access is denied. Respond with WWW-Authenticate in the latter case. Use 403 Forbidden when the client has valid credentials but lacks sufficient permissions. Use 404 Not Found when the resource does not exist, or when confirmation of its existence is not authorized.

Use 410 Gone when the resource has been deleted permanently. Indicate retryability and prevent information leakage.