> For the complete documentation index, see [llms.txt](https://developer.vario-software.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.vario-software.de/documentation/rest-api/faq.md).

# FAQ

Frequently asked questions about API access, requests, data queries and custom fields.

## Calling the API

### What is my API base URL?

```
https://{subdomain}.vario.cloud/api/vario
```

`{subdomain}` is your own tenant subdomain — the one you use to reach your installation.

{% hint style="warning" %}
The server address shown at the top of the interactive [API Reference](https://developer.vario-software.de/api-reference) is an **internal placeholder** and is not reachable from outside. Don't copy it.
{% endhint %}

For the exact URL and the endpoints enabled for your installation, download the tenant-specific OpenAPI specification from your ERP in [support mode](https://help.vario-software.de/support/melden-von-problemen-in-vario-cloud/support-modus) — the `servers` entry holds the authoritative value.

→ [REST API Introduction](/documentation/rest-api/introduction.md)

### Every request fails with 403 Forbidden, even with a valid token. Why?

You are almost certainly missing a **`User-Agent` header**. The API rejects requests without one.

This is not arbitrary: the platform uses `User-Agent` to identify the calling app, which is what makes [webhook suppression](/documentation/webhooks/faq.md#how-do-i-stop-an-infinite-webhook-loop) work. The App Framework sends your `appIdentifier` as the value.

### What is the difference between the SSO URL and the API URL?

They are two different hosts and it is the single most common mix-up:

| Purpose                           | URL                                                                     |
| --------------------------------- | ----------------------------------------------------------------------- |
| Getting and refreshing **tokens** | `https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/token` |
| Making **API calls**              | `https://{subdomain}.vario.cloud/api/vario`                             |

→ [REST API Authentication](/documentation/rest-api/authentication.md)

### I'm getting 429 Too Many Requests.

You exceeded the rate limit of **40 requests per 6 seconds**. Pause and retry with a delay; continuing to burst keeps you throttled.

→ [Rate limiting](/documentation/rest-api/rate-limiting.md)

### What do 402, 403 and 422 mean?

| Status  | Meaning                                                                      |
| ------- | ---------------------------------------------------------------------------- |
| **402** | A **license** is missing or its limit is exceeded — at runtime               |
| **403** | A **permission** is missing, or your request had no `User-Agent`             |
| **422** | Validation failed — including a missing required license **at install time** |

## Reading and writing data

### How do I find the right field path for a query?

Don't look it up in documentation — **enumerate it**. The available groups, templates and field paths depend on your installation and change between versions, and a path copied from a document may not exist in your version.

→ [Don't guess field paths — ask the API](/documentation/fundamentals/vql.md#dont-guess-field-paths-ask-the-api)

The same principle applies to navigating to a related entity: there is a dedicated call that returns all entities with their relations, which is how you discover joins.

### Can an AI assistant help me with the API?

Yes. Install the **MCP-Server** app and connect Claude Code, Cursor, VS Code or any other MCP client to a development tenant. The assistant then looks up endpoints and payloads in the live OpenAPI specification, enumerates VQL field paths and runs test queries — instead of guessing from training data.

→ [AI Assistants (MCP)](/documentation/ai-assistants-mcp.md)

### What is the difference between `account.number`, `customer.number` and `accountingNumber`?

An **account** is the address. Numbers then exist **per business relationship** — an account can be a customer, a supplier and a sales agent at the same time, each with its own numbers.

| Path                        | Meaning                                             |
| --------------------------- | --------------------------------------------------- |
| `account.number`            | Address number — identifies the account itself      |
| `customer.number`           | Customer number, valid in the customer relationship |
| `customer.accountingNumber` | The bookkeeping (FiBu) customer number              |
| `customer.ourNumber`        | **Your** supplier number, as the customer knows you |
| `supplier.number`           | Supplier number, valid in the supplier relationship |
| `supplier.accountingNumber` | The bookkeeping (FiBu) supplier number              |
| `supplier.ourNumber`        | **Your** customer number, as the supplier knows you |

The pattern is symmetric, so you can reason about any of them:

* `number` — the partner's number in that relationship,
* `accountingNumber` — its counterpart for financial accounting,
* `ourNumber` — the number the partner uses for *you*.

{% hint style="info" %}
For accounting exports this matters: the export uses the relationship's `accountingNumber` and falls back to `number` when it is empty. Writing an identifier into the wrong one silently changes which account a booking lands on.
{% endhint %}

### My paged query returns duplicates and misses rows.

You are paging over an **unsorted** result set. Offset paging is undefined without an order: pages overlap, some rows arrive twice and others never arrive — differently on each run. The backend adds no default order.

Always sort by a **unique** column (`id` is the safe choice), and deduplicate afterwards as a safety net.

### Why is `moreElements` never `true`?

Because it is a **string**. Pagination information arrives in response headers and is exposed as strings — compare with `=== 'true'`, not as a boolean.

→ [VQL](/documentation/fundamentals/vql.md)

### How do I store my own data on ERP records?

With [Custom Fields](/documentation/fundamentals/custom-fields.md). Attach them to articles, accounts, documents, listings and more, then query them by path:

```sql
SELECT id, custom.myapp.externalId
  FROM article.query
 WHERE custom.myapp.externalId NOTNULL
```

This is the standard way to store external reference IDs and sync state.

### How do I get IntelliSense for the API and for scripting?

Install the [`@vario-software/types`](https://www.npmjs.com/package/@vario-software/types) package — it provides type definitions for the platform, including the API schemas and the scripting interfaces.


---

# 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://developer.vario-software.de/documentation/rest-api/faq.md?ask=<question>&goal=<user_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.