Error codes

All errors share a consistent JSON envelope:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or no longer recognized.",
    "param": null,
    "request_id": "req_01J..."
  }
}

request_id is also echoed in the response headers — please quote it in support tickets.

Auth errors

Code	HTTP	Meaning
`MISSING_AUTH`	401	No `Authorization` header sent.
`INVALID_API_KEY`	401	Key not found.
`REVOKED_API_KEY`	401	Key was revoked.
`WRONG_AUTH_TYPE`	401	Sent an API key to a dashboard endpoint, or a Clerk JWT to a product endpoint.
`INVALID_CLERK_TOKEN`	401	JWT failed signature, expiry, or issuer checks.
`ACCOUNT_NOT_FOUND`	404	Clerk user has no Nordva Launch account. Call `POST /v1/auth/provision`.

Validation and quota

Code	HTTP	Meaning
`VALIDATION_ERROR`	400	Body or query fails schema. `param` names the offending field.
`INVALID_PLAN`	400	Plan name not recognised (must be `indie` or `builder`).
`RATE_LIMITED`	429	Plan rate limit exceeded. `Retry-After` header included.
`PLAN_LIMIT_REACHED`	403	Monthly quota exhausted. Upgrade or wait for the cycle to reset.
`PLAN_UPGRADE_REQUIRED`	403	Feature gated to a higher plan.
`NOT_FOUND`	404	Resource missing or owned by another project.
`CANNOT_EDIT_PUBLISHED`	409	Tried to edit a published changelog entry.
`HOSTNAME_ALREADY_REGISTERED`	409	Custom hostname already registered to another project.
`IDEMPOTENCY_CONFLICT`	409	Same `Idempotency-Key` used with a different request body.

Billing

Code	HTTP	Meaning
`BILLING_NOT_CONFIGURED`	503	Server-side Paddle environment is not configured.
`NO_BILLING_ACCOUNT`	404	Account has no Paddle customer yet — must complete a checkout first.
`BILLING_PORTAL_UNAVAILABLE`	502	Paddle portal-session API call failed. Retry shortly.

Custom domains

Code	HTTP	Meaning
`CUSTOM_DOMAIN_NOT_CONFIGURED`	503	Server-side Cloudflare for SaaS env not configured.
`CUSTOM_DOMAIN_LIMIT_REACHED`	403	Reached the per-plan custom hostname limit.

Publishable keys

Code	HTTP	Meaning
`KEY_INSUFFICIENT_PERMISSIONS`	403	A publishable key (`nv_pub_`) was used on a secret-only endpoint. Publishable keys are browser-safe and may only write to the public endpoints listed in Authentication — list, read, delete, and admin operations require a secret key (`nv_live_` / `nv_test_*`).
`API_KEY_LIMIT_REACHED`	422	Project already has the per-plan maximum of active keys of the requested type. Secret and publishable keys are counted independently. Revoke an unused key of the same type, or upgrade the plan.

Project slug

Code	Status	Meaning
`INVALID_SLUG`	422	Slug is not 1–40 lowercase letters, numbers and hyphens.
`SLUG_TAKEN`	409	The slug is in use, reserved, or was released by another project in the last 30 days.
`SLUG_CHANGE_LIMIT_REACHED`	429	The slug was already changed twice in the last 30 days. `remediation` gives the date it can change again. Old links keep working in the meantime.

Revenue, contacts and waitlist emails

Code	Status	Meaning
`STRIPE_NOT_CONNECTED`	409	No Stripe account is connected to this project. Connect one in the dashboard.
`STRIPE_ALREADY_CONNECTED`	409	Disconnect the current key before connecting another.
`STRIPE_KEY_NOT_RESTRICTED`	422	The key is not a restricted key (`rk_live_` / `rk_test_`). If a secret key was pasted, roll it in Stripe.
`STRIPE_KEY_INVALID`	422	Stripe did not recognise the key.
`STRIPE_KEY_MISSING_PERMISSION`	422	A required read permission is missing. `remediation` carries Stripe’s message naming it.
`STRIPE_CONNECTION_LIMIT_REACHED`	403	Indie includes one Stripe connection per account; Builder one per project.
`STRIPE_CONNECT_NOT_CONFIGURED`	503	Server-side encryption key for Stripe connections is not configured.
`CONTACT_NOT_FOUND`	404	No contact with that id in this project.
`EMAIL_TEMPLATE_INVALID`	422	Unknown placeholder, missing required placeholder, or empty/too long subject or body. `param` is `subject` or `body`.

System

Code	HTTP	Meaning
`INTERNAL_ERROR`	500	Unexpected server error. Include the `request_id` in your report.
`TURNSTILE_FAILED`	400	Cloudflare Turnstile token verification failed.

If you hit a code not listed here, please open an issue — we keep the canonical list at packages/api/src/lib/errors.ts.