Skip to content

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:

  1. 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 separate version field. A bare name or an npmjs.com URL is not a valid identifier.
  2. Scoped npm packages: pkg:npm/@scope/name (URL-encoded %40 is also accepted).
  3. PyPI names are normalized per PEP 503 — pkg:pypi/Jinja2 and pkg:pypi/jinja2 are equivalent.
  4. 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.