Designing Error Responses for REST and GraphQL
A consistent and well-designed error model is one of the most important, yet often overlooked, aspects of API development. Predictable error responses simplify client-side error handling, reduce support requests, and make your application more resilient. In this article, we'll explore how to create a unified error model for both REST and GraphQL services.
Consistent Error Format
Unifying your error responses across all APIs allows clients to handle different error types with a single logic. Use a standard error envelope that includes the following fields in every error response:
- **`code`**: An immutable, programmatic error code that the client can use to branch logic (e.g., `INVALID_INPUT`).
- **`message`**: A human-readable error message that can be displayed to the end-user.
- **`details`**: Additional context about the error, such as which fields were invalid or a correlation ID for debugging.
HTTP Semantics
Using the correct HTTP status codes is essential for adhering to the RESTful nature of your API. Use **4xx** status codes for client-side errors (e.g., 400 Bad Request, 404 Not Found) and **5xx** for server-side errors (e.g., 500 Internal Server Error). Avoid returning a `200 OK` status code with an embedded error state in the response body. This is semantically incorrect and complicates client-side error handling.
GraphQL Error Management
GraphQL handles errors differently from REST. You should preserve the standard GraphQL error format and add domain-specific details to the **`extensions`** field. This allows clients to handle both general GraphQL errors and specific application-level errors. Document and version your custom error codes just as you would for a REST API.
Testing and Validation
Ensure that your API's error responses behave as expected by writing tests for all error scenarios. Keep your sample error responses up to date and use the JSON Prettier tool to format them for better readability in your documentation.