Skip to main content
Was this helpful?

Authentication Errors

Authentication errors appear in the browser console or API responses when PrimeCal cannot verify who you are (401 Unauthorized) or knows who you are but will not allow the action (403 Forbidden). This page explains each error code you are likely to encounter and how to resolve it.

HTTP 401 — Unauthorized​

A 401 response means the request did not include a valid authentication token, or the token provided was rejected.

"Session expired. Please sign in again."​

Backend message: tokenExpired
Why it happens: Your JWT access token has reached its expiry time. The automatic refresh attempt failed (usually because the refresh token itself has also expired).
Fix: Sign out and sign back in. A fresh token pair is issued on successful login.

No token present​

Why it happens: The browser lost the stored token — this can happen after clearing localStorage, switching browsers, or a logout from another tab.
Fix: Sign in again. The token is stored in the browser's localStorage under the auth key.

Token validation failed (API key requests)​

Why it happens: If you are using a personal API key to call PrimeCal endpoints, the key may have been deleted, regenerated, or revoked. The api_access feature must also be included in your plan.
Fix: Go to Settings → API Keys, check whether the key exists and is active. Regenerate if necessary.

HTTP 403 — Forbidden​

A 403 response means you are authenticated but not authorized. PrimeCal uses several distinct 403 sub-codes.

{ "code": "FEATURE_NOT_ENTITLED" }​

Why it happens: Your subscription plan does not include the feature you attempted to use. This is enforced by FeatureAccessGuard when ENABLE_SUBSCRIPTIONS=true.
Example: Calling the Automation API when your plan does not include the automation feature.
Fix: Check Settings → Subscription for your current plan's features. Upgrade to a plan that includes the required feature, or ask your administrator to assign it.

{ "code": "PLAN_LIMIT_REACHED" }​

Why it happens: Your plan allows the feature but you have reached a numeric cap. For example, the Free plan allows up to 5 calendars and 3 automation rules.
Example response:

{
  "code": "PLAN_LIMIT_REACHED",
  "limitKey": "max_calendars",
  "limit": 5,
  "current": 5
}

Fix: Delete an existing resource (calendar, automation rule, sync account, or API key) to free up a slot, or upgrade your plan for a higher or unlimited cap.

"Admin access required"​

Why it happens: You attempted to access an admin-only endpoint (e.g., GET /api/admin/users) without the admin role.
Fix: Contact your system administrator. Admin role is assigned at the database level and cannot be self-assigned.

"Unauthorized" (agent / API key scope mismatch)​

Why it happens: When using the API with a personal API key or agent token, the key may not have the required scope to perform the requested action.
Fix: Review the API key's allowed scopes in Settings → API Keys and adjust, or use a key with broader permissions.

HTTP 429 — Too Many Requests​

Why it happens: PrimeCal enforces rate limits to protect the service. If you make too many requests in a short period, subsequent requests are rejected with 429.
Response includes: A Retry-After header indicating when requests will be accepted again.
Fix: Wait for the duration indicated by Retry-After, then retry. Reduce polling frequency if you are building an integration.

Still stuck?​

  • Copy the full response body from the failing API call (F12 → Network tab → click the request → Response tab) and look for the code field.
  • See Login Problems if you cannot sign in at all.
  • Contact support if the error persists after trying the fixes above.