API Troubleshooting 101: Commonly used Status codes and their meanings

Troubleshooting can be one of the most frustrating experiences for a developer, especially when error messages are difficult to interpret. Status codes are important to know because they can help in troubleshooting when interacting with web applications.

How can you debug an error if you cannot even identify it?

I have written down some of the most commonly used status codes and what they mean.

What are Status Codes?

Status codes are three-digit numbers returned by servers in response to a client’s request, indicating the result of the requests. Status codes are categorized based on the value of their first digit.

Status Codes Categories

1. 1xx Status codes - Informational Responses

These codes indicate that the server has received the request and is continuing the process

• 100 Continue: This indicates that the initial request was received and the client should continue.

• 101 Switching Protocols: The server agrees to switch protocols as requested by the client.

2. 2xx Status codes - Success Responses

These responses indicate that the server received, understood, and processed a request successfully

• 200 OK: The request was successful.

• 201 Created: A new resource was successfully created as a result of the request.

• 202 Accepted: The request was accepted for processing, but it may still be in progress.

• 204 No Content: The request was successful, but there’s no content to return.

3. 3xx Status Codes - Redirection Responses

These codes tell the client that further action is required to complete the request, often by redirecting it to a different URL.

• 301 Moved Permanently: The resource has been permanently moved to a new location.

• 302 Found: The resource temporarily resides at a different URL.

• 304 Not Modified: The resource hasn’t changed since the last request, so the client can use its cached version.

4. 4xx Status Codes - Client Error Responses

These codes indicate an error on the client’s side. This could be due to incorrect request formatting, unauthorized access, or an unresolvable resource.

• 400 Bad Request: The server couldn’t understand the request due to invalid syntax.

• 401 Unauthorized: Authentication is required, and it was either not provided or failed.

• 403 Forbidden: The client doesn’t have permission to access the resource.

• 404 Not Found: The server couldn’t locate the requested resource.

• 429 Too Many Requests: The client has made too many requests in a given time frame and should wait.

5. 5xx Status Codes - Server Error Responses

These codes indicate that the server failed to process a valid request, typically due to an internal issue or resource limitations.

• 500 Internal Server Error: A generic error message indicating the server encountered an unexpected condition.

• 502 Bad Gateway: The server received an invalid response from an upstream server.

• 503 Service Unavailable: The server is temporarily unavailable, often due to maintenance or overload.

• 504 Gateway Timeout: The server didn’t receive a timely response from an upstream server.

How Status Codes Are Used in API Development

1. Error Handling and Debugging: Status codes help both the client and the developer understand why a request failed and how to handle it. For instance, a 404 Not Found indicates the client may need to verify the URL, while a 500 Internal Server Error suggests a server issue.

2. Guiding Client Actions: Certain status codes prompt the client to take action. For example, a 401 Unauthorized may lead to a reauthentication attempt, while a 301 Moved Permanently should prompt the client to update its stored URLs.

3. Optimizing Client-Server Communication: Codes like 304 Not Modified help reduce server load by allowing clients to use cached resources rather than requesting data unnecessarily.

4. Rate Limiting: Codes like 429 Too Many Requests allow servers to control traffic and prevent abuse, ensuring fair usage and performance stability.

Best Practices for Using HTTP Status Codes

1. Choose the Right Code: Select the most precise status code for the situation. For example, use 404 Not Found only when the resource truly doesn’t exist, and 403 Forbidden if access is denied despite valid authentication.

2. Provide Descriptive Responses: Along with the status code, it’s helpful to return a JSON body containing additional details about the error, especially for 4xx and 5xx codes. This can clarify the issue for the client and ease troubleshooting.

3. Rate Limit Gracefully: If you use 429 Too Many Requests, also provide information on how long the client should wait before trying again. This can be done with headers like Retry-After.

4. Handle Redirects Thoughtfully: When using 3xx codes, ensure the client has enough context (e.g., redirect URL) to follow through as expected.

Conclusion

Thank you for reading! If you found this article helpful and informative, please subscribe and give it a like; it helps support the content and keep you updated with future posts.