Skip to content

Troubleshooting

ScopeboundUnavailableError: provision failed: 404 Not Found

The role name or UUID doesn't exist on your enforcement plane.

Fix: Create the role first via the management API or check the role name spelling.

curl -X POST https://your-partner.api.scopebound.ai/mgmt/v1/roles \
  -H "X-Scopebound-API-Key: sb-your-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "invoice-processor", "allowed_tools": ["read_invoices"]}'

ScopeboundUnavailableError: provision failed: 401 Unauthorized

The API key is wrong or not set.

Fix: Check SCOPEBOUND_API_KEY is set correctly in your environment.

echo $SCOPEBOUND_API_KEY   # should start with sb-

ScopeboundDenyError: SCOPE_VIOLATION

The tool name is not in the role's allowed_tools list.

Fix: Either add the tool to the role, or check that the tool name matches exactly (case-sensitive).

curl https://your-partner.api.scopebound.ai/mgmt/v1/roles?name=invoice-processor \
  -H "X-Scopebound-API-Key: sb-your-key"

ScopeboundDenyError: RATE_LIMIT_EXCEEDED

The session has exceeded the role's rate limit.

Fix: Wait for the rate limit window to reset (per-minute resets every 60 seconds, per-hour resets every 3600 seconds). Or increase the limits on the role.

ScopeboundDenyError: SESSION_EXPIRED

The session JWT has expired (default TTL is 3600 seconds).

Fix: The SDK automatically re-provisions on expiry. If you're managing JWTs manually, call /v1/provision again.

Enforcement plane returns 000 or connection refused

The enforcement plane is not running or the URL is wrong.

Fix: Check SCOPEBOUND_BASE_URL and verify the enforcement plane is healthy.

curl https://your-partner.api.scopebound.ai/healthz
# → {"status": "ok", ...}

Webhook not receiving events

  1. Check webhook_url is set on your role via GET /mgmt/v1/roles
  2. Verify your server returns a 2xx response — Scopebound retries once on failure
  3. Check the X-Scopebound-Signature header — verify it with your webhook_secret
from scopebound.adapters.mcp import webhook
webhook.Verify(payload, secret, signature)  # returns True if valid

Need help?

Email us at contact@scopebound.ai — we respond within the hour for design partners.