Troubleshooting Guide

HTTP 401 response when calling api.iio.space/v1/chat/completions

# Check your header format — must be exactly:
Authorization: Bearer YOUR_KEY
# NOT: Bearer: YOUR_KEY
# NOT: API-Key: YOUR_KEY

# Verify your key is active:
curl https://api.iio.space/v1/models \
  -H "Authorization: Bearer YOUR_KEY"
# Should return 200 with model list

# If still failing: request new key from operator

API returns 429. Happens when requests exceed tier limits.

# Check your tier limits:
# Free:  1,000 req/month
# Pro:   50,000 req/month
# Enterprise: unlimited

# Add retry with exponential backoff:
import time
def call_with_retry(client, **kwargs):
    for attempt in range(3):
        try:
            return client.chat.completions.create(**kwargs)
        except Exception as e:
            if '429' in str(e):
                time.sleep(2 ** attempt)
            else:
                raise

HITL gate has been pending for hours. Approver hasn't responded.

# 1. Check who the approver is:
from iio_governance import HITLGate
gate = HITLGate(api_url="https://api.iio.space")
result = gate.check("gate.production-deploy")
print(f"Approver: {result.approver}")
print(f"Timeout: {result.timeout_hours}h")
print(f"Created: {result.created_at}")

# 2. Notify via Matrix
# → In #iio-hitl room: "@operator HITL gate pending"

# 3. After timeout (default 48h), gate auto-blocks
# → Escalate to Node Operator

Python import fails after installation.

# Ensure you're using the right Python environment:
which python3
pip install iio-governance --upgrade

# Verify installation:
python3 -c "import iio_governance; print(iio_governance.__version__)"

# If using virtualenv:
source venv/bin/activate
pip install iio-governance

from iio_governance.langchain import get_iio_tools fails.

# Install with LangChain extras:
pip install iio-governance[langchain]

# Verify:
python3 -c "from iio_governance.langchain import get_iio_tools; print('OK')"

POL-001 to POL-004, POL-010, POL-011 fail. Seen in development environments.

# These 6 failures require production server setup:
# POL-001: /var/log/iio-audit doesn't exist locally
# POL-002/003: Audit ledger (production only)
# POL-004: Backup log (production only)
# POL-010: /etc/intelego/iio-rest-api.env (production only)
# POL-011: oauth2-proxy port 4181 (production only)

# For local development: 17/23 PASS is normal
# For production setup: see LAUNCH-OPERATOR-BRIEFING.md