Understanding HTTP Status Codes with Python Requests

Oct 22, 2023 ยท 5 min read

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:

  • 1xx Informational
  • 2xx Success
  • 3xx Redirection
  • 4xx Client Error
  • 5xx Server Error
  • Common codes you'll see include:

  • 200 OK - The request succeeded
  • 400 Bad Request - The request had invalid syntax
  • 401 Unauthorized - Authentication is required
  • 403 Forbidden - Access to the resource is forbidden
  • 404 Not Found - The resource could not be found
  • 500 Internal Server Error - The server encountered an unexpected error
  • 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
    

    Browse by tags:

    Browse by language:

    Tired of getting blocked while scraping the web?

    ProxiesAPI handles headless browsers and rotates proxies for you.
    Get access to 1,000 free API credits, no credit card required!