AUTH_REQUIRED | 401 | No | The request has no valid Clerk session or API key. | Sign in, mint an API key, or attach Authorization: Bearer <token> and retry. |
FORBIDDEN | 403 | No | The caller is authenticated but does not own the resource or lacks the required role. | Use an account that has access. Check RBAC scope on /api-reference/api-keys. |
ONBOARDING_REQUIRED | 403 | No | The user has not completed the activation contract (Day 1 interview + Week 1 org map). | Send the user through /onboarding/welcome. |
PLAN_LIMIT_REACHED | 402 | No | The account has hit a plan ceiling (products, members, or feature gate). | Move up a plan. See /api-reference/billing/create-checkout-session. |
CREDIT_EXHAUSTED | 402 | No | The monthly credit pool is empty for this billing cycle. | Move up a plan, or wait for the next reset. Check /api-reference/user/get-usage-and-quota. |
FEATURE_GATED | 403 | No | The feature exists on a higher tier than the caller’s current plan. | Move up a plan to unlock. |
SCORING_FAILED | 500 | Yes | The scoring engine could not produce a result. The site may be too large or scripted. | Retry with a simpler URL, or point the read at a different page. |
SCORING_TIMEOUT | 504 | Yes | The scoring run exceeded the time budget. | Retry. If it persists, point the read at a leaner page. |
SCORING_RATE_LIMITED | 429 | Yes | More than 5 score calls in the trailing 60-second window. | Back off 60 seconds, then retry. See Rate Limits. |
CRAWL_FAILED | 502 | Yes | The public-web crawl could not reach the URL. | Confirm the URL is public and reachable. Retry. |
CRAWL_TIMEOUT | 504 | Yes | The crawler hit the per-page time budget. | Retry, or point at a faster page. |
EMPTY_CRAWL | 422 | Yes | The crawler reached the URL but found no scoreable content. | Point at the main product page, not a marketing redirect. |
INTEGRATION_DISCONNECT | 401 | No | The integration’s OAuth token expired or was revoked. | Reconnect the integration in Settings > Integrations. |
TEAM_INVITE_EXPIRED | 410 | No | The invite token has aged out. | Ask an admin to resend the invite. |
SIGNAL_VALIDATION_FAILED | 400 | Yes | A signal-card submission missed required fields. | Complete the assessment, then retry. |
SIGNAL_RATE_LIMITED | 429 | Yes | A signal card was generated for the same target within the last hour. | Wait an hour, then retry. |
READ_ONLY_MODE_ACTIVE | 403 | No | The Free account hit the day-14 activation cliff with one or both onboarding milestones still incomplete. Write actions are blocked until rescue. | Finish the day-1 interview AND the week-1 org map (rescue path), or move up to Pro. See Path C+ activation contract. |
NETWORK_ERROR | 502 | Yes | An upstream dependency was unreachable from the API. | Retry with backoff. |
INTERNAL_ERROR | 500 | Yes | Unhandled exception inside the API. The trace was sent to Sentry. | Retry once. If it persists, ping support with the request ID. |