> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/products/billing/errors.md). # Billing errors How the Billing operations use the shared error codes: what a missing entity returns, which fields a Billing error has, and the errors of the my\* operations. The Billing operations return errors in the shared Navixy GraphQL API format, using the same codes as every other product. Consult this page if you call the Billing [my\* operations](/docs/navixy-graphql-api/products/billing.md#purpose-and-capabilities) for your workspace: the operations named with the prefix `my`, such as [mySubscribe](/docs/navixy-graphql-api/products/billing/api-reference/subscription.md#mysubscribe) and [myBalance](/docs/navixy-graphql-api/products/billing/api-reference/balance.md#mybalance), that act in the workspace named by your token. It covers where Billing differs from the other products in the use of shared codes. For the response structure, the full list of codes, and general scenarios, see [Error handling](/docs/navixy-graphql-api/error-handling.md). ## Missing entities Billing never returns `NOT_FOUND`. A missing entity is reported in one of 2 ways, depending on where the ID appears. A query by ID returns `null`, with no entry in `errors`: `node(id:)` returns `null` for a submission of another workspace, and [myInvoice](/docs/navixy-graphql-api/products/billing/api-reference/invoice.md#myinvoice) returns `null` for an invoice that doesn't exist or belongs to another workspace. [myBalance](/docs/navixy-graphql-api/products/billing/api-reference/balance.md#mybalance) never returns `null`. When a workspace has no balance, the first read opens one at zero. A mutation that names an entity that doesn't exist returns `VALIDATION_ERROR`. The entity and the ID are in `detail`, and there is no `field`, because a rule of the service rejected the reference rather than the input parsing. Send [mySubscribe](/docs/navixy-graphql-api/products/billing/api-reference/subscription.md#mysubscribe) with a plan ID that Billing doesn't know, and the response will be: ```json { "errors": [{ "message": "Plan not found: 019a6b2f-793e-807b-8001-42504c4e0009", "path": ["billing", "mySubscribe"], "extensions": { "type": "https://api.navixy.com/errors/validation", "title": "Validation Error", "status": 400, "detail": "Plan not found: 019a6b2f-793e-807b-8001-42504c4e0009", "instance": "/graphql", "code": "VALIDATION_ERROR", "traceId": "0af7651916cd43dd8448eb211c80319c", "timestamp": "2026-09-28T10:45:00Z" } }], "data": { "billing": { "mySubscribe": null } } } ``` The name in the message is the entity, `Plan`, not the GraphQL type `BillingAvailablePlan`. ### How to handle a missing entity Treat `null` from a query and `VALIDATION_ERROR` with "not found" in `detail` from a mutation the same way: the entity isn't available to your token. For a plan, read [myAvailablePlans](/docs/navixy-graphql-api/products/billing/api-reference/plan.md#myavailableplans) again and send an ID from one of its rows. For an invoice, read [myInvoices](/docs/navixy-graphql-api/products/billing/api-reference/invoice.md#myinvoices) again and take the `id` from it. ## IDs of the wrong type Every Billing ID names its entity type. A plan ID sent where a branch ID belongs, or a UUID that Billing didn't issue, is refused before any lookup, with `VALIDATION_ERROR` and `field` naming the input field, for example, `input.planId`. Read `field` to find the argument to fix. The IDs you send to [mySubscribe](/docs/navixy-graphql-api/products/billing/api-reference/subscription.md#mysubscribe) come from [myAvailablePlans](/docs/navixy-graphql-api/products/billing/api-reference/plan.md#myavailableplans), so send `planId` and `branchId` as they came, each in its own field. ## Fields of a Billing error A Billing error has the standard fields of [Error handling](/docs/navixy-graphql-api/error-handling.md#error-response-structure), with 2 differences: * `field` is present when the input itself failed, such as a malformed ID, and absent when a Billing rule rejected the request, such as a plan that the workspace may not take or a product that an active subscription already covers. Branch on `code`, and read `detail` for the reason. * `entityType` and `entityId` are never present on a Billing error. ## Errors of the my\* operations The `my*` operations return these codes:
CodeWhen it occursHow to resolve
PERMISSION_DENIEDThe token has no workspace_id claim, or the claim isn't a workspace ID. The my* operations read only that claim and don't fall back to your memberships. Or the roles the token carries give no access to the Billing product; the message is then Access Denied.Request a token issued for the workspace. See How the API picks your workspace and What your roles and products allow.
VALIDATION_ERRORThe plan or the branch isn't one that myAvailablePlans offers the workspace, the branch belongs to another plan, or an active subscription already covers a product of the plan.Read myAvailablePlans and mySubscriptions again. To cancel or move a subscription, contact Navixy at sales@navixy.com.
VALIDATION_ERRORAn ID is malformed or of the wrong type, first is above 100, or, on mySubscribe, the workspace_id claim names a workspace that this deployment doesn't have.Read field and detail.
RATE_LIMITEDMore than 100 requests in 60 seconds from one user, the subject of the token, or from one client address when the requests carry no token.Wait for the seconds in the Retry-After header, then retry. See Limits.
A request without a workspace claim returns this error on every Billing field it selects: ```json { "errors": [{ "message": "the token carries no workspace, so there is nothing for this operation to act on", "path": ["billing", "myAvailablePlans"], "extensions": { "type": "https://api.navixy.com/errors/forbidden", "title": "Permission Denied", "status": 403, "detail": "the token carries no workspace, so there is nothing for this operation to act on", "instance": "/graphql", "code": "PERMISSION_DENIED", "traceId": "0af7651916cd43dd8448eb211c80319c", "timestamp": "2026-09-28T10:45:00Z" } }], "data": null } ``` ### How to handle a missing workspace claim Request a token issued for the workspace whose billing you read. A token that works for Business Data Repository can still be refused here, because the Billing `my*` operations don't use your memberships. ## See also * [Error handling](/docs/navixy-graphql-api/error-handling.md): Learn the error structure, every code, and the common scenarios across the API. * [Choosing a plan and subscribing](/docs/navixy-graphql-api/products/billing/guides/choosing-a-plan-and-subscribing.md): Subscribe a workspace to a plan and handle the errors of [mySubscribe](/docs/navixy-graphql-api/products/billing/api-reference/subscription.md#mysubscribe). * [Reading balance and statement](/docs/navixy-graphql-api/products/billing/guides/reading-balance-and-statement.md): Read a balance and its statement. * [Reading invoices](/docs/navixy-graphql-api/products/billing/guides/reading-invoices.md): Read a workspace's invoices and handle a `null` invoice. * [Authentication](/docs/navixy-graphql-api/authentication.md): Learn how the token names the workspace that every operation acts in. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://navixy.com/docs/navixy-graphql-api/products/billing/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.