# Limits and troubleshooting

!!!danger Private beta: access through the IAMP platform only
The Quable MCP server is a **private beta** and **not a public API**. Access is only authorized through the **IAMP platform**: any other access is not authorized. **Any tool, prompt, resource, parameter or behavior can change or be removed at any time, without notice.**
!!!

---

## Rate limits

The limits below are those of the beta and can change at any time. The MCP server limits the number of requests to protect your instance and other customers:

| Scope | Limit |
| --- | --- |
| Per instance (`X-Quable-Instance`) | 30 requests per second, bursts up to 60 |
| Per IP address | 30 requests per second, bursts up to 60 |

A request over the limit is rejected with a `Rate limit exceeded` error. The assistant can retry after a short pause.

Each tool call makes one or more calls to the [Quable REST API](/quable-api/get-started/), which has its own limits. If the REST API answers `429 Too Many Requests`, the tool returns an error: wait and retry, or ask the assistant to work in smaller batches.

---

## Size limits

Tool results must fit in the AI model's context, so large contents are capped. When a result is cut, it says so explicitly (`truncated: true`, `too_large: true` or a text note): the assistant is never given partial data presented as complete.

| What | Limit | When exceeded |
| --- | --- | --- |
| Search results | 50 items per page | Use `limit` and `offset` to page. |
| Pagination depth | `page × limit` ≤ 100,000 | Error: narrow the search, use a smaller `limit` or reverse the sort. |
| Asset download (`get_asset_file`) | 10 MiB | Images and PDFs fall back to the preview rendition, with a note. A CSV returns its first rows. A spreadsheet returns an error. |
| PDF text | 75,000 characters | Text cut, `truncated: true` and `total_chars`. |
| CSV / spreadsheet | 2,000 rows per sheet, 100 columns, 20 sheets, 75,000 characters in total | Sheets cut, `truncated: true` and `total_rows`. |
| Spreadsheet parsing | 30 seconds | Error. |
| Export file download | 5 MB (zip) | Metadata only. |
| Export file returned inline | 250 KB (unzipped) | Metadata only, `too_large: true`. Use `upload_location`, reduce the scope or download from the Quable interface. |

---

## Caching

Product, variant, asset and export data are **never cached**: a read after an update always returns the current data.

---

## Errors

Tool errors are written to be understood by the assistant: they say what was wrong and how to fix it, for example the expected JSON format or the tool to call to find a valid code. The assistant usually corrects its call by itself.

| Error | Meaning |
| --- | --- |
| Validation error | A parameter is missing or invalid, or a value would not be stored by the PIM. Nothing was written. |
| Not found | The product, asset, variant or code does not exist. Check the code, not the label. |
| `401` / authentication error | The token is invalid, expired or revoked. |
| `403` / forbidden | The token does not allow this action, e.g. a write with a *Read access* token. |
| Rate limit exceeded | Too many requests, see [Rate limits](#rate-limits). |
| Upstream error or timeout | The Quable API did not answer correctly. Retry later; if it persists, [contact us](/contact-us/). |

---

## Troubleshooting

#### Missing required headers

The instance name or the token is missing. Check the Quable MCP server settings of your agent in the IAMP platform, see [Access](/mcp-server/connect/).

#### Invalid instance format

The `X-Quable-Instance` value contains uppercase letters, digits or other characters. Use only `a-z` and `-`, exactly as in your Quable URL, without `.quable.com`.

#### 401 on every tool call

The token is invalid, expired or was revoked. Create a new one in **System → API token** and update it in the IAMP platform. Check that the token belongs to the instance named in `X-Quable-Instance`.

#### Read tools work but write tools fail

You are using a *Read access* token. Use a *Full access* token if you want the assistant to modify data.

#### The assistant does not see any Quable tool

Check that the Quable MCP server is enabled for your agent in the IAMP platform, with your instance name and token. Access from any other client is not authorized.

#### The assistant uses wrong codes or says an attribute does not exist

Run the `pim-bootstrap` prompt at the start of the session, and ask the assistant to look up codes with `list_attributes`, `list_predefined-values` or `search_classification` instead of guessing them. Results of `get_product` and `search_products` only contain the sections requested: check `_meta.views.omitted` before concluding data is missing.

#### A link to the PIM is broken

`get_pim_url` needs the numeric `legacy_id` returned by another tool, not the product or asset code. Ask the assistant to use the `legacy_id` from the last result.

#### The export file is not returned

The file is larger than 250 KB once unzipped. Reduce the scope (fewer columns, locales or products), use `upload_location` to deliver it to an FTP/SFTP server, or download it from the Quable interface.

---

## Need help?

[Contact us](/contact-us/) with the time of the request, the instance name and the tool name. Never send your API token.
