Troubleshooting
Every error Retiform returns carries a code. Find the code below: each entry says what caused it,
whether a trial limit was involved, and what to do next. An error that names a limit also gives
limit, allowed and current, so you can see how far over you are.
If an error is not listed here, or the step does not help, check the status page and write to
support with the code and the time of the call.
A tool or option the changelog describes is missing. This one has no error code. Your agent keeps the
tool descriptions it read when it connected, and a release that adds a parameter to a tool does not change
the ones it already has. Quit the agent and start it again: a reconnect alone may not refresh them. Until
then, the agent can still send the new parameter, and Retiform applies it.
AUTHENTICATION_REQUIRED: No credential was sent
- HTTP status
- 401
- Message
- Authentication is required.
- Cause
- The request carried no access token, so the service cannot tell who is calling.
- Next step
- Sign in again from your agent so it sends a token; in Claude Code, reconnect the Retiform MCP server.
TOKEN_EXPIRED: The access token has expired
- HTTP status
- 401
- Message
- The credential has expired.
- Cause
- Access tokens are short-lived, and this one is past its expiry time.
- Next step
- Reconnect or sign in again; your agent obtains a fresh token.
TOKEN_UNTRUSTED: The access token is not accepted
- HTTP status
- 401
- Message
- The credential is not trusted.
- Cause
- The token was issued for another service or audience, or the identity it names is disabled.
- Next step
- Check that your agent connects to the address from your invitation, then sign in again; if it persists, ask a tenant administrator whether your access is still active.
INSUFFICIENT_SCOPE: The token lacks a needed permission
- HTTP status
- 403
- Message
- The caller lacks the required scope.
- Cause
- The call needs a scope, such as kg:write, that was not granted when your agent signed in.
- Next step
- Reconnect and grant the requested access; the tool reference lists the scope each tool needs.
ORIGIN_NOT_ALLOWED: Browser requests are refused
- HTTP status
- 403
- Message
- requests from a browser origin are not accepted
- Cause
- The MCP endpoint does not accept requests sent from a web page.
- Next step
- Connect from an MCP client such as Claude Code or VS Code agent mode, not from a browser.
TENANT_LIMIT: The trial has no room for another member or agent client
- HTTP status
- 409
- Message
- The tenant has reached its limit for this.
- Cause
- The trial's member or agent client limit is reached. Your administrator sees this in the console.
- Next step
- Remove a member or agent client you no longer need, then try again.
| Limit | HTTP status | Next step |
|---|
| Members | 409 | Remove a member or cancel a pending invitation, then invite again. |
| Agent clients | 409 | Remove the agent client you no longer use, then add the new one. |
NOT_IN_PLAN: Not part of the trial
- HTTP status
- 403
- Cause
- The trial leaves this capability out: its limit is zero.
- Limit
- Service applications
- Next step
- Connect your agent as an agent client instead; the quickstart shows how.
PLAN_LIMIT_REACHED: A trial limit is reached
- Cause
- The trial's limit named in the error's limit field is reached. The error also gives allowed and current; a monthly limit gives a Retry-After time. Nothing was written.
- Next step
- Follow the step for the limit below. To ask for more room, reply to your invitation email or write to support@retiform.ai. Paid plans with higher limits are opening soon.
| Limit | HTTP status | Next step |
|---|
| Retrieval calls | 429 | This month's retrieval calls are spent; retry after they reset at the start of the next month (UTC). |
| Memory entries | 409 | Neither the console nor kg can delete a memory entry yet, and a correction adds a version that counts as well, so ask for more room as above. |
| Entities | 409 | Delete entities you no longer need, then try again. |
| PDF pages read | 429 | This month's PDF pages are spent; upload a shorter PDF or text, or retry after the reset at the start of the next month (UTC). |
DOCUMENT_CAP_REACHED: The trial's document storage is full
- Cause
- The upload would pass the trial's document count or stored text, or too many document jobs are already running; the error's limit field says which.
- Next step
- Delete documents you no longer need on the console's Documents page and upload again; if the limit is a job limit, wait for a running job to finish and upload the same document again. To ask for more room, reply to your invitation email or write to support@retiform.ai. Paid plans with higher limits are opening soon.
| Limit | HTTP status | Next step |
|---|
| Documents | | Delete documents you no longer need, then upload again. |
| Stored text | | Delete or shorten documents to free stored text, then upload again. |
DOCUMENT_TOO_LARGE: The document is too large
- Cause
- The upload is over a size limit: the request size for text, the file size for a PDF or Word file, or the longest text one revision may hold. The error's limit, allowed and current fields say which.
- Next step
- Split the document into smaller parts and upload each part as its own document; the error's allowed field gives the largest size accepted.
| Limit | HTTP status | Next step |
|---|
| Upload size (text) | 413 | Split the text into smaller parts and upload each part as its own document. |
| Upload size (Word and PDF) | 413 | Split the PDF or Word file into smaller files, or upload its text instead. |
DOCUMENT_TOO_MANY_PAGES: The PDF has too many pages
- HTTP status
- 422
- Cause
- The PDF has more pages than one document may have. The error's allowed and current fields give the limit and the file's page count. Nothing was stored, and no pages were counted against the month's allowance.
- Limit
- Pages in one PDF
- Next step
- Split the PDF into smaller files and upload each as its own document.
EMBEDDING_ALLOWANCE_EXHAUSTED: Search, context and recall are keyword-only for the rest of the month
- Cause
- The trial's monthly embedding allowance is spent, so search, context assembly and memory recall return keyword matches only and mark their results with this warning. It is a warning, not an error.
- Limit
- Embedding tokens
- Next step
- Keep working with keyword search, phrasing questions with words the documents use; semantic search returns when the allowance resets at the start of the next month (UTC).
RATE_LIMITED: Too many requests
- HTTP status
- 429
- Message
- The request rate limit has been reached.
- Cause
- Requests arrived faster than the rate limit allows.
- Limit
- Request rate and quota
- Next step
- Wait as long as the response says, then retry: the Retry-After header over REST, or the error's retryAfterSeconds from an MCP tool.
QUOTA_EXCEEDED: The request quota is spent
- HTTP status
- 429
- Message
- The request quota has been reached.
- Cause
- The request quota for the current period is spent.
- Limit
- Request rate and quota
- Next step
- Wait as long as the response says, then retry: the Retry-After header over REST, or the error's retryAfterSeconds from an MCP tool.
BUSY: The service is busy
- Cause
- Your trial's storage is busy with another write, or a schema change holds the type the call uses.
- Next step
- Retry the same call shortly; the error gives a time to retry after. Check the status page if it persists.
UNAVAILABLE: Temporarily unavailable
- Cause
- A dependency the call needs did not answer in time, or the feature is switched off for the trial, such as entity extraction.
- Next step
- Retry shortly; if the error names a disabled feature, use the call without it. Check the status page if it persists.
INVALID_ARGUMENT: A call argument is not accepted
- Cause
- An argument is missing, malformed or out of range; the error names it and what is accepted.
- Next step
- Correct the argument as the error says and call again.
NOT_FOUND: Not found
- Cause
- No document, memory entry or other record with that identifier exists in your trial.
- Next step
- Check the identifier; find entries with recall_memory and passages with assemble_context.
CONFLICT: The record changed or is in use
- Cause
- The call conflicts with the record's current state, for example a document job that already finished or an identifier another upload holds.
- Next step
- Read the record's current state and call again with it.
TYPE_MISSING: A type the call needs is missing
- Cause
- The trial's schema lacks a type the call uses, such as Document or MemoryEntry.
- Next step
- Ask a tenant administrator to apply the starter schema or restore the missing type.
RESPONSE_TOO_LARGE: The answer is too large to return
- Cause
- The result is over the response size a tool may return.
- Next step
- Ask for less, for example a smaller token budget or fewer results, and call again.
CONFIRMATION_REQUIRED: The change needs confirmation
- Cause
- The call would delete or replace data, so it needs an explicit confirmation.
- Next step
- Review what the call will change, then call again with the confirmation the error asks for.
INTERNAL_ERROR: Something went wrong on our side
- Message
- the platform failed to complete the call
- Cause
- The service failed to complete the call.
- Next step
- Retry once; if it fails again, check the status page and write to support with the time of the call.
DOCUMENT_EMPTY: The document has no text
- HTTP status
- 422
- Cause
- Nothing but whitespace was left once the document was converted to text, for example HTML holding only scripts or styles.
- Next step
- Check that the file has readable text in the format you named, then upload it again.
DOCUMENT_ENCODING_INVALID: The document is not valid text
- HTTP status
- 422
- Cause
- The content is not valid Unicode, often because a binary file was sent as text.
- Next step
- Save the document as UTF-8 text, Markdown or HTML and upload it again.
DOCUMENT_TOO_COMPLEX: The HTML is nested too deeply
- HTTP status
- 422
- Cause
- The HTML has more nesting or more elements than Retiform reads in one document.
- Next step
- Simplify the page or split it into several documents, or upload its text as Markdown.
MEMORY_ENTRY_SUPERSEDED: That memory entry is no longer current
- Cause
- Only the current entry of a memory chain can be superseded. The error names the entry that replaced it and the chain's current entry.
- Next step
- Supersede the entry named in currentEntry instead.
MEMORY_CHAIN_FULL: The memory chain is full
- Cause
- A memory chain holds at most 100 versions, and this one has them all.
- Next step
- Record the fact as a new entry with record_memory.
MEMORY_TYPE_CONFLICT: Memory is unavailable in this tenant
- Cause
- The tenant's schema already has its own MemoryEntry type, so Retiform's memory type was not added.
- Next step
- Ask a tenant administrator about the tenant's own MemoryEntry type.
MEMORY_SOURCE_NOT_CITED: That memory entry does not cite the document
- Cause
- A confirmation names the document it was checked against, which must be one of the documents the entry's cited passages come from. The answer is the same whether or not the document exists.
- Next step
- Confirm with the documentId of one of the entry's citedPassages (the part before the first colon).
MEMORY_REVISION_NOT_CURRENT: That is not the document's current revision
- Cause
- A confirmation holds only against the document as it is now. The error gives the current revision, or says the document was deleted.
- Next step
- Check the entry against currentRevision and confirm that revision. For a deleted document, check the entry still holds and confirm without a revision.
MEMORY_CONFIRMATIONS_UNAVAILABLE: Confirmations are not available for this tenant yet
- Cause
- The tenant's memory type is still being brought to the version that stores confirmations.
- Next step
- Retry after retryAfterSeconds. If it keeps happening, ask the tenant's administrator.
MEMORY_REVIEWS_UNAVAILABLE: Accepting entries is not available for this tenant yet
- Cause
- The tenant's memory type is still being brought to the version that stores reviews.
- Next step
- Retry after retryAfterSeconds. If it keeps happening, ask the tenant's administrator.
MEMORY_MEMBERS_ONLY: Only a person reviews new entries
- Cause
- The list of entries new since you last looked, marking them as seen, and accepting an entry belong to a person's sign-in: they are a person's review of what agents recorded. An agent's token was used.
- Next step
- Sign in as a person in the console. From an agent, use recall_memory, and correct an entry with supersede_memory.
- Cause
- No embedding model is configured, so search returns keyword matches only and marks its results with this warning. It is a warning, not an error.
- Next step
- Keep working with keyword search; if it persists, write to support.
PROVIDER_TIMEOUT: Search is keyword-only: the embedding model was slow
- Cause
- The embedding model did not answer in time, so this result uses keyword matches only and carries this warning. It is a warning, not an error.
- Next step
- Retry the call shortly for semantic results; check the status page if it persists.
PROVIDER_UNAVAILABLE: Search is keyword-only: the embedding model is unavailable
- Cause
- The embedding model could not be reached, so this result uses keyword matches only and carries this warning. It is a warning, not an error.
- Next step
- Retry later for semantic results; check the status page if it persists.
MEMORY_ENTRY_IN_CHAIN: Only a standalone memory entry can be deleted
- Cause
- The entry is part of a supersession chain, and deleting one version would break the chain's history.
- Next step
- Correct the chain by superseding its current entry with supersede_memory instead of deleting a version.
NO_KEYWORD_TERMS: Results matched by meaning only
- Cause
- The question had no word that keyword search can use, so the results were matched by meaning only and carry this warning. It is a warning, not an error.
- Next step
- Rephrase the question with words your records use for a keyword match as well.
SECRET_DETECTED: The text holds a credential
- HTTP status
- 422
- Message
- The document contains a credential of kind github-token at line 3, column 7; remove it and send again
- Cause
- The memory entry, document, entity or extraction text you sent contains a credential of a kind Retiform refuses, such as an API key or a private key. The error names the kind and where it starts, and for an entity the property, never the credential itself. Nothing was stored. In a bulk import only the item holding it is rejected.
- Next step
- Remove the credential from the text and send it again. If it was ever stored or shared, rotate it with its provider. See Credentials in what you write for the kinds found.