Python API Authentication and Errors

Authentication proves the caller's identity. The API's documentation says which scheme it uses:

Read credentials from environment variables or a secrets manager, never from source code. Prefer headers to query parameters, since URLs end up in server logs and browser history. Always use https://: over plain HTTP, tokens travel unencrypted.

A requests.Session can hold the header so every call includes it: session.headers["Authorization"] = f"Bearer {token}".

Once the API knows who you are, it checks whether you are allowed to do what you asked. The two outcomes have different status codes:

• 401 Unauthorized really means unauthenticated: the credentials are missing, invalid or expired. Fix: check the token is set, correctly formatted and current; refresh it if it's short-lived.
• 403 Forbidden means the credentials are valid but lack permission for this action or resource. Fix: request the right scope or role, or use an account that has it. Retrying won't help.

if response.status_code == 401:
    raise PermissionError("Token missing or expired: check CLUB_API_TOKEN")
if response.status_code == 403:
    raise PermissionError("This token can't edit rides; ask an admin for the rides:write scope")

Tokens are usually issued with limited scopes, such as read-only access to rides. Request the smallest scope your program needs: if the token leaks, the damage is limited to what it could do.

A request can fail at three different stages, and each calls for a different response:

try:
    response = session.get(url, timeout=10)
    response.raise_for_status()
    rides = response.json()["rides"]
except requests.Timeout:
    print("The club API didn't answer in time")
except requests.HTTPError as error:
    print("API returned", error.response.status_code)
except (requests.JSONDecodeError, KeyError):
    print("Unexpected response format")

One catch-all except Exception: print("API error") hides which case occurred, so nobody knows whether to wait, fix the token or update the code.

Retry only failures that are temporary and operations that are safe to repeat:

• Retry: timeouts and connection errors on reads, 429 Too Many Requests, 502, 503 and 504.
• Don't retry: 400, 401, 403, 404 or 422, which will fail the same way every time.
• Be careful with POST and other writes. If the request reached the server but the response was lost, retrying can repeat the action, such as charging a membership fee twice. Retry writes only when the API supports an idempotency key, a unique id you send so the server ignores duplicates.

Wait between attempts with exponential back-off (1, 2, 4 seconds...), cap the number of attempts, and respect a Retry-After header when the server sends one. requests can do this for you with urllib3's Retry class:

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry = Retry(total=3, backoff_factor=1, status_forcelist=[429, 502, 503, 504],
              allowed_methods=["GET"])
session.mount("https://", HTTPAdapter(max_retries=retry))

Task: build a client with external credentials, explicit timeout handling and bounded retries for safe reads.

import os, time
import requests

def get_rides(url, attempts=3):
    token = os.environ["CLUB_API_TOKEN"]
    headers = {"Authorization": f"Bearer {token}"}
    for attempt in range(1, attempts + 1):
        try:
            response = requests.get(url, headers=headers, timeout=10)
        except (requests.Timeout, requests.ConnectionError):
            if attempt == attempts:
                raise
        else:
            if response.status_code in (429, 502, 503, 504) and attempt < attempts:
                pass                                  # temporary: retry below
            else:
                response.raise_for_status()           # 401/403/404 fail immediately
                return response.json()
        time.sleep(2 ** (attempt - 1))                # 1 s, then 2 s
    response.raise_for_status()

Only GET requests are retried, the number of attempts is capped, and 401 or 403 raise straight away because waiting won't fix them. For the worked check: can a valid token still lack permission for an operation? Yes. That's a 403, an authorization failure.

The requests documentation covers authentication, and urllib3 documents Retry. Continue with a simple web server and revisit environment configuration. Practise with the Python exercises and Python quiz.