permission_denied

HTTP status: 403
Category: API authorisation

What this error means

Your request was authenticated, but the caller is not permitted to perform this action. The API rejected the operation because of missing scopes, insufficient relationships, plan limits, or tenant status.

Related codes: forbidden, insufficient_scope, tenant_inactive, feature_not_available, feature_unavailable, and quota_exceeded.

Common causes

• API key scoped to users:read but calling a write endpoint
• OAuth token missing required scopes for the operation
• SpiceDB permission check denied for the target resource
• Tenant suspended or on a plan that does not include the feature
• Plan quota exceeded (users, webhooks, applications, etc.)

How to fix it

1. Review API key scopes in Console → Settings → API keys and add the required scope.
2. For OAuth, request the correct scopes during authorisation.
3. Verify resource-level permissions with permissions.check() or the Console.
4. Confirm the tenant is active and on a plan that includes the feature.
5. Do not retry without changing permissions — 403 responses are not transient.

Example

import { GreetPermissionError } from "@wocha/sdk";
 
try {
  await wocha.users.create({ email: "user@example.com" });
} catch (err) {
  if (err instanceof GreetPermissionError) {
    if (err.errorCode === "insufficient_scope") {
      console.error("Add users:write scope to your API key");
    } else if (err.errorCode === "quota_exceeded") {
      console.error("Plan quota reached — upgrade or remove unused resources");
    } else {
      console.error(err.errorCode, err.requestId, err.docsUrl);
    }
  }
}

See also

• permission_denied (legacy) · quota_exceeded