Errors

{
  "error": "<stable_code>",
  "message": "<human readable, English, may change>",
  "trace_id": "<16-hex>",
  "...": "code-specific extras"
}

{
  "error": "invalid_api_key",
  "message": "API key not recognised",
  "trace_id": "8b3a47ce91d04f17"
}

{
  "error": "upgrade_required",
  "message": "This endpoint requires the 'see' tier",
  "feature": "clusters",
  "current_tier": "watch",
  "required_tier": "see",
  "upgrade": true,
  "trace_id": "8b3a47ce91d04f17"
}

{
  "error": "topic_denied",
  "message": "Key not authorised for topic 'cyber'",
  "requested_topic": "cyber",
  "allowed_topics": ["global"],
  "trace_id": "8b3a47ce91d04f17"
}

{
  "error": "validation_error",
  "message": "Request body failed validation",
  "fields": [
    { "loc": ["body", "terms", 0, "type"], "msg": "value is not a valid enum member" },
    { "loc": ["body", "name"],              "msg": "field required" }
  ],
  "trace_id": "8b3a47ce91d04f17"
}

{
  "error": "rate_limited",
  "message": "Rate limit exceeded — retry after 7s",
  "retry_after_seconds": 7,
  "limit_rpm": 30,
  "trace_id": "8b3a47ce91d04f17"
}

{
  "error": "watchlist_limit_reached",
  "message": "Your tier allows up to 4 watchlists",
  "current_tier": "see",
  "limit": 4,
  "current": 4,
  "trace_id": "8b3a47ce91d04f17"
}

{
  "error": "service_unavailable",
  "message": "Backing store is degraded — try again shortly",
  "retry_after_seconds": 5,
  "trace_id": "8b3a47ce91d04f17"
}

def render_error(envelope: dict) -> str:
    code = envelope["error"]
    if code == "upgrade_required":  return f"Upgrade to {envelope['required_tier']} for {envelope['feature']}"
    if code == "topic_denied":      return f"This topic isn't in your plan. You have: {envelope['allowed_topics']}"
    if code == "key_expired":       return "Your trial expired. Renew at [email protected]"
    if code == "rate_limited":      return f"Slow down — try again in {envelope['retry_after_seconds']}s"
    return envelope["message"]  # fallback

try:
    r = httpx.get(url, headers=h)
    r.raise_for_status()
except httpx.HTTPStatusError as e:
    body = e.response.json()
    log.error("intel api error",
              extra={"status": e.response.status_code,
                     "code":   body.get("error"),
                     "trace":  body.get("trace_id")})
    raise

RETRYABLE = {"rate_limited", "service_unavailable", "upstream_error",
             "upstream_timeout", "internal_error"}

def is_retryable(envelope: dict) -> bool:
    return envelope.get("error") in RETRYABLE