Status Codes
HTTP response status codes indicate whether a specific HTTP request has been successfully completed. They are grouped into five classes: * **1xx**: Informationa...
Definition
HTTP response status codes indicate whether a specific HTTP request has been successfully completed. They are grouped into five classes:
- 1xx: Informational responses.
- 2xx: Success (e.g., 200 OK, 201 Created).
- 3xx: Redirection (e.g., 301 Moved Permanently).
- 4xx: Client Errors (e.g., 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests).
- 5xx: Server Errors (e.g., 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout).
Why It Exists
Status codes allow developers to implement automated logic for handling different server responses. For example, catching a 429 code tells your client to apply rate limit backoff, whereas a 503 code signals that the provider's server is down, prompting you to switch to a backup model immediately.
How It Works
STATUS ROUTING TREE
┌────────────────────────┐
│ Read Response Status │
└───────────┬────────────┘
│
┌──────────────────┼──────────────────┐
[Status == 200/201] [Status == 429] [Status == 5xx]
│ │ │
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
│ Process JSON │ │ Backoff/Wait │ │ Switch LLM │
│ Payload │ │ before retry │ │ Provider │
└───────────────┘ └───────────────┘ └───────────────┘
1. **Header Parsing**: The client reads the numeric code returned in the HTTP response headers before parsing the body payload.
2. **Error Raising**: If the code is $\ge 400$, the client raises a network exception, skipping normal execution flow.Real-World Example
In Gemini SDK, if your monthly budget threshold is exceeded, the API returns a response with status code 429 (Too Many Requests). The Python client detects this status and raises a specific exception containing the rate limit warning message.
Python Example
Here is a response processing client that handles status codes dynamically:
import httpx
from typing import Dict, Any
class ModelAPIClient:
"""Handles status-specific routing logic for external endpoints."""
def process_response(self, response_code: int) -> Dict[str, Any]:
if 200 <= response_code < 300:
return {"action": "parse", "message": "Success"}
elif response_code == 401:
return {"action": "abort", "message": "Invalid API Key. Update headers."}
elif response_code == 429:
return {"action": "retry", "message": "Rate limit exceeded. Apply backoff."}
elif response_code >= 500:
return {"action": "failover", "message": "Server error. Route to backup model."}
return {"action": "raise_unknown", "message": f"Unexpected status: {response_code}"}
if __name__ == "__main__":
client = ModelAPIClient()
print("Code 200:", client.process_response(200))
print("Code 429:", client.process_response(429))
print("Code 503:", client.process_response(503))Interview Questions
- Beginner: What status code represents a resource that was not found?
- Intermediate: What is the difference between 401 Unauthorized and 403 Forbidden?
- Advanced: Under what conditions will an LLM API client receive a 504 Gateway Timeout, and how should your backend manage this event?
Interview Answers
- Beginner: A 404 Not Found status code represents a resource that could not be located on the server.
- Intermediate: 401 Unauthorized means the client has not authenticated (credentials are missing or invalid). 403 Forbidden means the client is authenticated but does not have permission to access that specific resource.
- Advanced: A 504 Gateway Timeout occurs when an upstream server (such as an LLM provider's generation node) fails to return a response to the API gateway within the configured timeout window. A production backend should handle this by catching the timeout exception, returning a user-friendly error message, and logging the event to alert system monitoring tools.
Common Mistakes
- Returning 200 for errors: Returning an error message inside a successful response:
{"status": "error", "code": 500}with an HTTP status code of 200 OK. This prevents standard API gateways and client libraries from handling errors correctly. Always match the HTTP status code to the response context.
Assignment
Write a Python script using httpx that makes a request to a URL and prints a custom error message for codes 404, 429, and 500.