Understanding HTTP Status Codes with Python Requests

Making HTTP requests is a fundamental task in many Python applications. Whether you're accessing APIs, web scraping, or building web services, you'll need to send requests and handle responses. One of the most important aspects of an HTTP response is the status code. Let's dive into what these codes mean and how to use them properly in Python.

What Are HTTP Status Codes?

HTTP status codes are 3-digit numbers returned with every HTTP response. They indicate whether the request was successful or not, and provide details about what happened. Status codes are useful for understanding responses, handling errors, and debugging issues.

The first digit defines the class of response:

Common codes you'll see include:

There are over 70 HTTP status codes covering various response scenarios. Refer to the full list of HTTP status codes for details on specific codes.

Checking Status Codes in Python Requests

The Python Requests library provides a simple interface for making HTTP calls. You can check status codes on the response object.

Here's an example GET request:

import requests

response = requests.get('<https://api.example.com/data>')

To access the status code, use the status_code attribute:

print(response.status_code)
# 200

This prints the 3-digit status code number. You can also use the reason attribute to print the status description:

print(response.reason)
# OK

So for a successful 200 response, this would print "OK".

Handling Response Status Codes

You'll want to handle different status code classes appropriately in your application.

For 2xx success codes, you can proceed to work with the response data. For example:

if response.status_code == 200:
    # Success - parse response content
    data = response.json()

For 4xx client errors like 404 or 401, you may want to throw an exception or handle the error case cleanly:

if response.status_code == 404:
    raise NotFoundError("Resource could not be found")

And for 5xx server errors, you may want to retry the request or handle the outage:

if response.status_code == 500:
    # Retry request
    response = requests.get(url)

So check the status code on every response and handle the different classes properly in your application.

Common Python Requests Status Code Scenarios

Let's go through some specific examples of status codes you're likely to encounter.

200 OK

A 200 OK is the standard success response. It means the request was received, understood, and processed successfully.

response = requests.post('<https://httpbin.org/post>', data={'key':'value'})
print(response.status_code)
# 200

This indicates everything worked as expected.

404 Not Found

A 404 means the resource could not be found. This could happen if you request an invalid URL or a resource that no longer exists.

response = requests.get('<https://api.example.com/invalid-endpoint>')
print(response.status_code)
# 404

For 404 errors, you may want to handle it gracefully or log the bad request.

429 Too Many Requests

A 429 response indicates rate limiting. This means you've sent too many requests too quickly and the server temporarily blocked you.

response = requests.get('<https://api.example.com/data>')
print(response.status_code)
# 429

The rate limit will be lifted after some time. You'll want to handle 429s by slowing down requests.

5xx Server Errors

Any 500-range code indicates a server error. This means the request is valid but the server had an internal error processing it.

response = requests.get('<https://api.example.com/data>')
print(response.status_code)
# 500

For 500 errors, retry the request a few times or handle the outage temporarily in your code.

Conclusion

HTTP status codes provide meaningful insight into API responses. In Python Requests, check response.status_code to access the code and response.reason for a description. Handle the various status code classes properly, accounting for success 2xx, redirection 3xx, client errors 4xx, and server errors 5xx. Knowing status codes will help you reliably parse responses and handle errors in your Python apps.

Frequently Asked Questions

How do I check if a Python request is successful?

Use response.status_code to get the status code. Codes 200-299 indicate success. You can also use response.ok:

if response.ok:
  # Request was successful

What does a 404 status code mean in Python?

A 404 status code indicates the requested URL or resource could not be found on the server. This is a common client-side error. Check for it with:

if response.status_code == 404:
  print('URL not found')

How can I handle 403 Forbidden errors in Python requests?

A 403 means access to the requested resource is forbidden. You may need to provide authentication or request permission. Handle it with:

if response.status_code == 403:
  # Handle lack of access

What is a 429 Too Many Requests status code in Python?

A 429 indicates rate limiting - you've sent too many requests and got temporarily blocked. You can handle it by slowing down:

if response.status_code == 429:
    # Add delay before retrying

What causes a 500 Internal Server Error in Python requests?

A 500 error means the server encountered an unexpected error and could not complete the request. This is a server issue. Handle it by retrying:

if response.status_code == 500:
   # Retry the request