Error Code Status
Understanding the different HTTP status codes is crucial for diagnosing and resolving issues within the API. Below are the status codes categorized by their types, with more detail provided for common ones that are used in this API.
2xx Success
| Code | Status | Description |
|---|---|---|
| 200 | OK | The request has succeeded. The information returned with the response is dependent on the method used in the request. |
| 201 | Created | The request has been fulfilled and has resulted in one or more new resources being created. |
| 202 | Accepted | The request has been accepted for processing, but the processing has not been completed. |
| 204 | No Content | The server has successfully processed the request, but is not returning any content. |
3xx Redirection
| Code | Status | Description |
|---|---|---|
| 301 | Moved Permanently | The requested resource has been assigned a new permanent URI and any future references to this resource should use one of the returned URIs. |
4xx Client Errors
| Code | Status | Description |
|---|---|---|
| 400 | Bad Request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). |
| 401 | Unauthorized | The request has not been applied because it lacks valid authentication credentials for the target resource. |
| 403 | Forbidden | The server understood the request but refuses to authorize it. |
| 404 | Not Found | The server cannot find the requested resource. Links that lead to a 404 page are often called broken or dead links and can be subject to link rot. |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the target resource. |
5xx Server Errors
| Code | Status | Description |
|---|---|---|
| 502 | Bad Gateway | The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request. |
Best Practices for Handling API Errors
When integrating with an API, it's essential to handle errors gracefully to ensure a better user experience and create more resilient applications. Here are some best practices to follow:
Understand and Categorise Errors:
Client-side Errors (4xx):
These errors are due to bad requests from the client. Make sure to inform users about what went wrong and how they can correct it. For instance, validate user input before sending requests to avoid 400 Bad Request errors, and ensure users are authenticated to prevent 401 Unauthorized errors.
Server-side Errors (5xx):
These issues originate from the server. Implement retry mechanisms and log these errors for further investigation. For transient errors like 502 Bad Gateway, consider implementing retries with exponential backoff.
Implement Robust Error Logging
Log all errors with relevant information such as timestamps, endpoints, request payloads, and user details. This helps in diagnosing issues and improving the API over time.
Graceful Error Handling and User Feedback
Provide clear and user-friendly error messages. Avoid technical jargon and suggest corrective actions when possible. For example, instead of saying "400 Bad Request," explain the issue in simple terms like "Invalid input. Please check your data and try again."
Retry Mechanisms for Transient Errors
Implement retry logic with exponential backoff for errors that might be transient. Ensure you avoid infinite retries to prevent overloading the server.
Use Circuit Breaker Patterns
For critical services, consider implementing a circuit breaker pattern to prevent cascading failures. This pattern helps isolate failures and provides fallback mechanisms.
By following these best practices, you can create a more robust and user-friendly application while interacting with APIs.