FAQ & Troubleshooting

Auth

401 "Could not validate credentials" — the JWT expired (access tokens are short-lived) or the API key is disabled. Frontends should call POST /auth/refresh with the refresh token; the official apps do this silently. API keys: check they weren't disabled under Settings → API keys.

403 email_unverified — confirm the verification email first. In local dev (AUTH_DEV_MODE=true) the token is returned by /auth/signup and logged by the backend.

428 sso_required — your email domain enforces SSO; follow the login_url in the error body instead of password login.

403 account_suspended — the account was suspended by a platform operator; contact support.

Limits & billing

402 plan_limit_reached — creating that entry/upload/invite/space would exceed a plan ceiling. The body names the metric, limit, and current used. Upgrade under Settings → Billing (or delete something).

429 api_quota_exceeded — the monthly API-call quota is spent. The response includes Retry-After; the SDK backs off automatically. Quotas reset at the start of each calendar month.

Content & delivery

A published change isn't showing — delivery serves the frozen published_fields snapshot; re-publish after editing. The SDK also caches for 30s by default (cache: false disables).

Localized field comes back empty — the requested locale has no value and no fallback chain reaches one. Configure fallbacks under Settings → Locales, or request locale=* to inspect the raw maps.

References arrive as ids, not objects — pass include: 1–3, then use resolve() / resolveLinks() from the SDK.

Preview shows drafts in production — you shipped a cms_pre_… token. Production sites must use delivery (cms_del_…) keys.

Local development

CORS errors in the browser — add your app's origin to the backend's CORS_ORIGINS env var (comma-separated).

AI endpoints return 503 — no provider configured. Set AI_PROVIDER — Groq and Gemini have free tiers; Ollama runs fully local. See .env.example.

Emails never arrive locally — without SMTP_* configured the backend logs email bodies to its console, and dev mode returns action tokens directly in API responses.

Webhook deliveries fail — check the per-webhook delivery log (status, response body). Endpoints must answer 2xx quickly; verify your signature check uses the raw request body.

Self-hosting

The repo runs fully local with docker compose up (Postgres + pgvector included), and the deployment guide walks through a zero-cost hosted setup on Vercel + Render/Railway + Neon/Supabase.

Still stuck? Head to Support.