Error Handling

# Python: branch on the status, then the code
def raise_for_homedata_error(response):
    """Raise for a failed response. Returns None when the record is absent."""
    err = response.json().get("error", {})

    # Shape 3: a plain string. Check before you call .get()
    if isinstance(err, str):
        message, code = err, ""
    else:
        message = err.get("message", "")
        # Codes are UPPER_SNAKE_CASE from the platform, lowercase from
        # endpoints, so always normalise before comparing
        code = (err.get("code") or "").upper()

    # Status first: it is always there, error.status is not
    if response.status_code == 403:
        # Not every 403 is a key problem. A key rejection always carries
        # INVALID_API_KEY; a plan restriction comes back as a bare string
        # with no code, and swapping the key will not fix it.
        if code == "INVALID_API_KEY":
            # A missing key arrives here too, not on 401
            raise AuthError(message)
        # Remove the filter or change plan. The key is not the problem.
        raise ApiError(f"403: {message}")
    elif response.status_code == 402:
        raise AllowanceError(message)  # retrying will not help
    elif response.status_code == 404:
        return None
    elif response.status_code == 400:
        # code may be "" on the plain-string shape
        raise ValidationError(code or "bad_request", message)
    else:
        raise ApiError(f"{response.status_code}: {message}")


response = requests.get(url, headers=headers)
# Raises, or gives back None when the record simply is not there
data = response.json() if response.ok else raise_for_homedata_error(response)

# Python: retry with backoff
import time

def api_call(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code in (503, 504):
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue
        # Anything else that failed goes through raise_for_homedata_error above,
        # so an error body is never returned as if it were data
        if not response.ok:
            # return, so a 404's None is not thrown away
            return raise_for_homedata_error(response)
        return response.json()
    raise Exception("Still failing after retries")