--- title: "Errors" description: "Every code the package refuses with: the fields it carries, the English label, the status an auth route answers with, and what to do about it." canonical_url: "https://nuxt-backend.dev/docs/reference/backend/errors" --- # Errors > Every code the package refuses with: the fields it carries, the English label, the status an auth route answers with, and what to do about it. A refusal from a package function is a `ConvexError` whose data is `{ code, ...fields }`. Convex sends that data to the client in production too, where any other error arrives as "Server Error". An auth route refuses with the same code and fields in its error body, at the status below. [`getBackendError(error)`](https://nuxt-backend.dev/docs/data/errors) reads both and returns `{ code, data, message }`. `BACKEND_ERRORS` in `nuxt-backend/functions` holds the catalog, and `test/unit/error-catalog.test.ts` keeps this page in step with it. `/e/` links to the code's entry below. `message` is the sentence to show: the throw site's own sentence for the person when it wrote one (`data.message`), else the code's label from the `errors` group. Some reasons have a label of their own (`errors._`), and a label with numbers in it is used only when the numbers are there. The English the deployment log shows is the error's `message` property, which production never sends to the client. Every field in `data` is optional on the read side, the required ones too: the reader keeps only the fields that fit the catalog, so check the one you use before you rely on it. ## Codes ### `unauthenticated`
Data Label Status Handling
message? Sign in to continue. 401 Show the message. If nobody is signed in, send the person to sign in, then retry.
Better Auth answers some of its own refusals with 401 too, and the reader maps them here with Better Auth's message: a wrong password on a sign-in form, for one, where the person is already on the sign-in page and only needs the message. ### `forbidden`
Data Label Status Handling
reason , message? You don't have access to this. 403 Show the message; reason says what would change the answer.
### `no_workspace`
Data Label Status Handling
message? Create or choose a workspace first. 409 Offer the workspace switcher, or create one.
### `rate_limited`
Data Label Status Handling
retryAfter? (ms), limit? , message? Too many requests. Try again in a moment. 429 Wait retryAfter , then retry. limit names the spent limit.
### `insufficient_credits`
Data Label Status Handling
meter? , balance , need , message? Not enough credits. Top up to continue. 402 Offer a credit pack or a plan with more credits.
With both amounts, the label reads "Not enough credits: {balance} left, {need} needed. Top up to continue." (`errors.insufficient_credits_amounts`). ### `invalid_input`
Data Label Status Handling
field , message? That input isn't valid. Check it and try again. 400 Mark field and show the message.
A checkout, a gift checkout, a plan change and the portal refuse what only the server may choose with this code: `productIds`, `productId` or `pack` outside the catalog (a plan change to a credit pack too), an `origin`, `successUrl` or `returnUrl` off the site, reserved `metadata` keys, a client's `trialInterval`, `trialIntervalCount` or `discountId`, a `trial` from server code that is not 1 to 30 days in days or weeks, and a `discountCode` the provider does not accept. See [What the server decides](https://nuxt-backend.dev/docs/billing/subscriptions/checkout#what-the-server-decides). ### `not_ready`
Data Label Status Handling
reason , message? Nothing to show yet. 409 Don't offer a retry: something has to happen first. reason says what (below).
### `unavailable`
Data Label Status Handling
service , reason , message? This isn't available right now. Try again shortly. 503 Retry later only for provider_refused ; the other reasons need the deployment fixed, and reason tells an operator what.
## Reasons The `forbidden` reasons the package throws:
Reason When
banned The account is banned.
role · permission The account's role lacks the role or the permission statement the call requires.
not_member · workspace_role The caller is not a member of the workspace, or lacks the workspace role.
admin_only A billing admin function ( refundOrder , the webhook log) and the caller is no admin.
not_owner The order, subscription or agent request belongs to another account, or the order does not exist: the two answer alike.
impersonating An administrator acting as this account tried something only its owner may do.
sign_in_refused canSignIn said no; its message is the one shown.
customer_taken With billTo: 'user' , the account's email already pays for another account (the provider keeps an individual customer's email unique); or the entity is mapped onto a customer from before 0.2 that another entity is keyed to.
not_billing_manager The billing portal of a workspace, opened by a member the provider does not list as its owner or a billing manager.
gift_refused · not_recipient · no_email A gift was refused (to the purchaser's own address, before their first paid order, or by canGift , whose message is the one shown), the gift is addressed to another email or does not exist, or the session has no verified email.
gift_refunded The gift's purchase was refunded before its claim, so there is nothing to receive.
A `forbidden` the reader maps from Better Auth's own 403 carries Better Auth's error code, lower-cased, as its `reason` (`you_are_not_allowed_to_ban_users`, say). Those reasons pass through as Better Auth names them: they are not in the table above and not covered by the stability promise. The `not_ready` reasons:
Reason When Label
no_customer The billing entity has no provider customer yet: the portal, a usage report or a refund needs one, and a first checkout creates it. Nothing to show yet — this opens after your first purchase.
no_catalog The app sells nothing yet: no catalog products, so a checkout, a gift or a plan change has nothing to sell. Declare plans and packs in billing.catalog.ts and run npx nuxt-backend billing sync . Nothing to buy yet — this app has no plans or packs set up.
not_paid A gift whose purchase is not paid yet can't be claimed. Nothing to show yet.
not_synced The credit balance never synced for this entity: no credits have reached it, or a mutation spent with allowRefresh: false . syncEntitlements or a credit pack changes it. Nothing to show yet — no credits have reached this account. Open billing to refresh, or get a credit pack.
The `unavailable` reasons, by service:
Service Reason When Retry?
billing not_configured BILLING_ACCESS_TOKEN is not set on the deployment. Label: "This isn't set up on this app yet." No
billing provider_refused The billing provider refused the request; the log has billing.provider_failed . Yes
email provider_refused The email provider refused a call (a segment, a contact, a broadcast); its words are in the error's message , for the log. Yes
email test_mode · unconfigured A code or an invitation would not arrive: the deployment is in test mode and the address is no test address, or it has no email key. The log has email.undeliverable . The message says the address can't receive mail here, or that the app can't send email yet. No
backend unexpected Never thrown: a composable's error reads a failure that carries no code this way (a function that crashed, which production words as "Server Error", or an app's own ConvexError ). It says nothing about whether a service is down. Its message is the app's own sentence when it wrote one, else the label "Something went wrong." See Composable conventions . Maybe
A `rate_limited` from a package limit names it in `limit`: `emailOtp`, `emailOtpGlobal`, `emailOtpAttempt`, `emailChange`, `billingSync`, `ai`, `aiBudget`, `admin`, `invitation`, `invitationGlobal` and `agentRegistrationGlobal` (see `DEFAULT_LIMITS` in `nuxt-backend/rate-limit`), and `discountCode`: the package's own count of discount codes the provider refused at checkout, ten per billing entity in a fixed one-hour window, kept whether or not the app passes a rate limiter. A code in flight counts until the provider answers, so parallel checkouts can't try more between them. And `gifts`: the gifts one purchaser bought in the `setupBilling({ giftLimit })` window, ten in thirty days by default. A limit of your own, enforced with `throws: true`, reads the same way. - API reference: [/docs/reference/api/functions](https://nuxt-backend.dev/docs/reference/api/functions) - Source: [https://github.com/qruto/nuxt-backend/blob/main/src/convex/errors.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/errors.ts) ## Sitemap See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.