Common mistakes
| Mistake | Why it's wrong | Do instead |
|---|---|---|
Calling /api/vai/* or /api/control/* without credentials | these are authenticated tiers → 401 Authentication required | send X-Session-Token (vai) or X-API-Key (control); the /api/v1/* tier needs none |
Posting the audit response's envelope block to an assess endpoint | the audit response returns envelope identifiers, not the full envelope | assess with the full EvidenceEnvelope.to_dict() (the sample-evidence.json shape) under {"evidence": …} |
Forgetting to wrap evidence in {"evidence": …} | the request model expects an evidence field | send {"evidence": {…}}; compliance also needs pack_id |
Sending an unknown pack_id | constrained by a Literal → 422 | use eu_ai_act, nist_ai_rmf, or iso_42001 |
| Expecting a provider API key to be sent by the client | keys are server-side only; clients never send them | set the key in the server env; enable the provider (local-first) |
Expecting /api/v1/registry/agents to paginate | it returns the full set with a count | paginate at your data layer; use /api/vai/* listings for limit/offset |
| Assuming role-based access on the session tier | the session guard accepts any valid session (no RBAC yet) | enforce authorization at your gateway if required (authorization) |
| Treating a mock result as an error | mock is the deterministic default when no live provider is enabled | check mode/provider; enable a live provider for real calls |
Retrying /api/auth/login in a tight loop | per-IP rate limit → 429 | back off; default is 20 attempts / 15 min |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 Authentication required | no credential on an authenticated tier | add X-Session-Token or X-API-Key; confirm the path tier |
401 Invalid or expired session | session TTL passed (8h default) or secret rotated | re-login via /api/auth/login |
403 API key has been revoked | valid key, but deactivated | issue a new key (cc_bootstrap_owner.py) |
422 with a detail array | request-body validation failed | read loc/msg; fix the field (missing input, bad pack_id, …) |
404 on an agent id | agent not observed, or registry lost on restart | the registry is in-memory, re-observe after a restart |
trust_level/risk_level is unknown | evidence lacked the structural sections | assess with a full envelope from a real audit |
| Sessions vanish after restart | SESSION_SECRET is ephemeral | set a fixed SESSION_SECRET (required in production) |
| App refuses to start | AUTH_COOKIE_SECURE=true with an ephemeral secret (V-F3 gate) | set SESSION_SECRET before enabling secure cookies |
| CORS error in the browser | CORS_ORIGINS too restrictive | add your origin to CORS_ORIGINS (JSON array) |
| Registry empty in the dashboard | nothing observed yet, or wrong API base | observe an agent; check the dashboard's API base URL |
503 from the Stripe webhook | webhook secret unconfigured | set the Stripe webhook secret, or ignore if billing is unused |
Still stuck? Confirm the tier (auth tiers), verify the exact request/response shape (conventions), and cross-check the endpoint (open / authenticated). For internals, see the engineering docs.