Troubleshooting — Soverenia¶
Published at docs.soverenia.com. Related: FAQ.
1. The request was rejected¶
Symptom: the API returns an error instead of a verdict.
Usual causes and fixes:
- Invalid package identifier. Use the Package URL format
pkg:<ecosystem>/<name>— e.g.pkg:npm/lodash,pkg:pypi/jinja2— and pass the version in the separateversionfield. A bare name or an npmjs.com URL is not a valid identifier. - Scoped npm packages:
pkg:npm/@scope/name(URL-encoded%40is also accepted). - PyPI names are normalized per PEP 503 —
pkg:pypi/Jinja2andpkg:pypi/jinja2are equivalent. - Unsupported ecosystem (e.g.
pkg:docker/...) — supported types: npm, pypi, maven, golang, cargo, nuget, gem, composer, hex, pub, conda, cocoapods, apk, deb, rpm.
2. Rate limited¶
Symptom: error RATE_LIMITED with a Retry-After hint.
Fix: slow down and retry after the indicated delay. Free tier allows 60 requests/minute (1000/day) per API key; higher limits are available on paid plans.
3. Authentication errors (401/403)¶
Symptom: request rejected as unauthorized.
Fix: check that you send a valid API key in the Authorization: Bearer sov_… header. Keys are issued per plan — the Enterprise plan manages keys in the dashboard.
4. The verdict looks wrong¶
Symptom: you disagree with a SAFE/UPGRADE/AVOID verdict.
Fix: every verdict response lists the underlying evidence records. Send us the package, version, expected verdict and your reasoning via the contact form on soverenia.com — we triage within 48 h.
5. Service status¶
Check status.soverenia.com — current status and incident history. If everything is operational and your issue persists, contact us via the form on the website.
Last updated: 2026-11. Published at docs.soverenia.com.