Errors

{
  "error": {
    "type": "<machine-readable category>",
    "message": "<human-readable explanation>"
  }
}

HTTP/1.1 401 Unauthorized
{
  "error": {
    "type": "authentication_error",
    "message": "Missing or malformed Authorization header. Expected: 'Authorization: Bearer <api_key>'."
  }
}

HTTP/1.1 400 Bad Request
{
  "error": {
    "type": "invalid_request_error",
    "message": "universe_id is not a valid UUID"
  }
}

HTTP/1.1 403 Forbidden
{
  "error": {
    "type": "permission_error",
    "message": "access denied: this universe does not belong to your account"
  }
}

HTTP/1.1 404 Not Found
{
  "error": {
    "type": "not_found",
    "message": "no data found for this metric/universe/date combination"
  }
}

HTTP/1.1 400 Bad Request
{
  "error": {
    "type": "invalid_request_error",
    "message": "invalid filter value (check `day` format YYYY-MM-DD)"
  }
}

import time, requests

def get(path, key):
    r = requests.get(f"https://verseodin.com/api/v1{path}",
                     headers={"Authorization": f"Bearer {key}"})

    if 200 <= r.status_code < 300:
        return r.json()

    body = r.json().get("error", {})
    err_type, msg = body.get("type"), body.get("message")

    if err_type == "rate_limit_error":
        time.sleep(int(r.headers.get("Retry-After", "5")) + 1)
        return get(path, key)
    if err_type == "authentication_error":
        raise PermissionError(f"check your VERSEODIN_API_KEY: {msg}")
    if err_type in ("permission_error", "not_found"):
        return None  # caller can decide
    if err_type == "invalid_request_error":
        raise ValueError(msg)
    raise RuntimeError(f"verseodin api {r.status_code} {err_type}: {msg}")