Limits and troubleshooting

By
The Quable Team

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, 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.
Upstream error or timeout The Quable API did not answer correctly. Retry later; if it persists, 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.

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.

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 with the time of the request, the instance name and the tool name. Never send your API token.