How to Interpret HTTP Response Codes in REST APIs

When you're working with REST APIs, every request you send gets a response. That response always includes an HTTP status code, and knowing how to interpret HTTP response codes is one of the most practical skills you can develop for API troubleshooting. Instead of guessing why something failed, the status code tells you exactly where to look.

This post covers what these codes mean, how they're organized, and how to use them to diagnose errors in your API calls.

How HTTP Response Codes Are Organized

HTTP status codes are three-digit numbers grouped into five classes. The first digit tells you the general category of the response:

• 1xx (Informational): The request was received and processing is continuing. You'll rarely see these in REST API work.
• 2xx (Success): The request was received, understood, and accepted successfully.
• 3xx (Redirection): Further action is needed to complete the request, often a redirect to a new URL.
• 4xx (Client Error): Something was wrong with the request you sent. This is your problem to fix.
• 5xx (Server Error): The server failed to fulfill a valid request. This is the API provider's problem.

That 4xx versus 5xx distinction matters a lot for troubleshooting. A 4xx means look at your code or credentials. A 5xx means the service itself is having an issue.

The Most Common Codes You'll Encounter

2xx: Success Responses

• 200 OK: The standard success response. Your GET request worked, or your request was processed normally.
• 201 Created: Your POST request succeeded and a new resource was created. You'll see this after creating a new device in a network management API.
• 204 No Content: The request succeeded, but there's nothing to return. Common after a DELETE operation.

4xx: Client Error Responses

• 400 Bad Request: Your request was malformed. Check your JSON syntax, parameters, or request body.
• 401 Unauthorized: You didn't authenticate, or your credentials are wrong. Check your API key or token.
• 403 Forbidden: You're authenticated, but you don't have permission for this action.
• 404 Not Found: The resource you requested doesn't exist. Check your URL and endpoint path.
• 405 Method Not Allowed: You used the wrong HTTP method. Maybe you sent a PUT when only POST is supported.
• 429 Too Many Requests: You've hit a rate limit. Slow down your requests.

5xx: Server Error Responses

• 500 Internal Server Error: Something went wrong on the server. Not your fault, but worth retrying after a moment.
• 503 Service Unavailable: The server is down or overloaded. Wait and try again later.

Reading Response Codes in Python

When you use the requests library in Python, the status code is always accessible on the response object. Here's a simple example that checks the code and handles common cases:

import requests

url = "https://sandbox.cisco.com/api/v1/devices"
headers = {"Authorization": "Bearer YOUR_TOKEN"}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print("Success:", response.json())
elif response.status_code == 401:
    print("Authentication failed. Check your token.")
elif response.status_code == 404:
    print("Resource not found. Check the URL.")
elif response.status_code >= 500:
    print("Server error. Try again later.")
else:
    print(f"Unexpected status: {response.status_code}")

You can also use response.ok to get a simple boolean that returns True for any 2xx response. For quick checks, that's often enough. For real troubleshooting, you want the actual code.

Using Status Codes to Diagnose Errors Systematically

When an API call fails, follow this order:

1. Check the status code class (4xx or 5xx) to know whose problem it is.
2. Read the response body, which often includes a message explaining the specific error.
3. Validate your request: URL correctness, proper HTTP method, valid headers, and correct JSON formatting.
4. Confirm authentication: Is your token valid? Has it expired?
5. Consult the API documentation for that specific endpoint and method.

Most REST APIs return a JSON body alongside the status code with additional detail. Don't just read the code; read the full response. The combination of the status code and the error message is what makes API troubleshooting fast and precise.

What's Next

Now that you can interpret HTTP response codes and use them to diagnose errors, the next step is understanding how data is structured inside those API responses. The next post in this series covers parsing JSON response bodies in Python, so you can extract exactly the information you need from API calls.