Use this runbook to diagnose and fix API errors rapidly in development and production environments.

---

1. 401 unauthorized

Diagnostic Checks

1. Header Format: Verify the header is Authorization: Bearer dike_live_xxxxxxxx (must have the Bearer prefix with a space).
2. Token Type Confusion: Ensure you are not sending a /account/login JWT session token to /v1/* routes or sending an API key to /account/* routes.
3. Revocation Status: Check the Developer Dashboard to confirm the key has not been deleted or revoked.

---

2. 403 plan_required

Cause

Occurs exclusively on POST /v1/reason when invoked using an API key on the Free Developer Plan.

Fix

Upgrade your account to Pay As You Go or Enterprise in the Developer Dashboard under Billing. /v1/search, /v1/cite, /v1/document/*, and /v1/graph/traverse continue to function on the Free tier.

---

3. 404 citation_not_found vs. 422 citation_unparseable

These two errors occur on POST /v1/cite but indicate different root causes:

---

4. 422 validation_error

Common Causes

• query or question string is empty or exceeds length constraints (1–1000 chars for Search, 5–2000 chars for Reason).
• top_k is outside the allowed range (1–50 for Search, 4–30 for Reason).
• depth on /v1/graph/traverse exceeds 3.
• filters.year_from or filters.year_to is outside 1800–2100.

---

5. 429 rate_limited

Fix

• Check response.headers['X-RateLimit-Reset'] to determine the exact second when your sliding window refreshes.
• Implement exponential backoff with jitter in your client SDK (see Rate Limiting Triage).

---

6. 503 upstream_unavailable

Cause

A downstream dependency (vector store, embedding inference node, or LLM reasoner) is experiencing a transient connection timeout.

Fix

• This is a server-side transient condition, not an invalid request.
• Retry automatically with exponential backoff (1s, 2s, 4s).

---

Next Steps

• Review Rate Limiting Triage.
• Diagnose empty reasoning answers in Weak Grounding Diagnostics.