> 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

## 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](#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.

### 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.vario-software.de/documentation/rest-api/faq.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.