Documentation Index
Fetch the complete documentation index at: https://cludo.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
This page covers common errors and pitfalls when integrating with the Cludo API.
Authentication Errors
401 Unauthorized
Common causes:
| Cause | Fix |
|---|
Missing Authorization header | Add Authorization: SiteKey {token} or Authorization: Basic {token} |
| Malformed base64 token | Verify your token encodes the correct format: customerId:engineId:SearchKey (SiteKey) or customerId:apiKey (Basic). Note: SearchKey is a fixed literal string. |
| Wrong auth scheme for the endpoint | Index management, crawler URL queues, and search tools require Basic authentication. See Authentication. |
| Wrong region | Verify that the base URL matches your customer ID range. See Regions. |
echo "Mzo2OlNlYXJjaEtleQ==" | base64 --decode
# Should output: 3:6:SearchKey
403 Forbidden
Common causes:
| Cause | Fix |
|---|
| SiteKey used for management endpoint | Use Basic (API Key) auth instead |
| Engine does not belong to customer | Ensure the engine ID in your token matches an engine owned by the customer ID |
| Feature is not enabled | For AI endpoints, confirm that AI Chat or AI Summary is enabled for the engine |
Wrong Region
Requests sent to the wrong region return 401 Unauthorized because credentials are validated against the regional account store. EU credentials are only valid on the EU base URL and US credentials are only valid on the US base URL.
Fix:
-
Check your customer ID:
- Below 10,000,000 → EU:
https://api.cludo.com
- 10,000,000 and above → US:
https://api-us1.cludo.com
-
Update the request base URL to match the customer ID range.
See Regions for full details.
Search Returns No Results
Symptom: Search returns totalDocument: 0 even though content exists.
Common causes:
| Cause | Fix |
|---|
| Wrong engine ID | Verify your engine ID in Dashboard → Engines |
| Content not yet indexed | Check crawl status in Dashboard → Crawlers. New content may take minutes to appear. |
| Filters too restrictive | Remove filters temporarily to confirm the query itself returns results |
| Wrong field names in filters | Field names are case-sensitive. Check available fields in your engine configuration. |
AI Chat / AI Summary Errors
These errors are specific to the AI Chat (/search/answer) and AI Summary (/search/summarize) endpoints.
403 Forbidden: “AiChat feature is not enabled”
AI Chat and AI Summary return 403 Forbidden when the respective feature is not enabled for the engine.
Fix: The AI feature must be enabled for your engine. Contact support or check your engine configuration in MyCludo.
422 Unprocessable Entity from AI Summary
AI Summary returns 422 Unprocessable Entity when the request is well-formed and reaches the model, but the selected search results do not contain enough relevant context to generate a useful summary.
Treat this as a completed request with no usable answer. Show a “no summary available” message instead of retrying immediately, then consider broadening the query, selecting more relevant sources, or checking whether the indexed content covers the topic.
AI returns no answer or a generic answer
The generativeAnswerAvailable field in the search response indicates whether AI can attempt an answer. If it returns false, AI will not generate a useful response.
Common causes:
| Cause | Fix |
|---|
| Query is too vague | Use specific, descriptive questions |
| Relevant content is not indexed | The page may exist on your website but not in the search index. Use the crawler URL test in MyCludo to verify. See Content Indexing Issues. |
| Crawler cannot access the content | The crawler may be blocked, the page may require JavaScript rendering, or the page may be excluded by crawler rules |
| Pushed content is incomplete | Ensure pushed documents include enough title, URL, and body/description content for AI to ground an answer |
| Canned response matched instead | Canned responses are checked before AI is invoked. Review your canned response configuration in MyCludo |
Content Indexing Issues
Pushed documents don’t appear in search
Symptom: Documents pushed via Index Management don’t appear in search results.
Common causes:
| Cause | Fix |
|---|
| Wrong crawler ID | Verify the crawler id in Dashboard → Engines. A crawler ID that does not exist for the customer returns 404 Not Found. |
| Missing required fields | Check Index Management for field requirements. |
| Document URL conflicts | If a document with the same URL already exists, it may need to be replaced (PUT) not appended |
Crawled pages don’t appear in search
If website pages aren’t being indexed, use the Test Crawler feature in MyCludo to diagnose why.
How to use Test Crawler:
- Log in to MyCludo
- Navigate to Crawlers and select your crawler
- Click the Test Crawler button
- Enter the URL you want to test and press Enter
What Test Crawler shows you:
| Result | Meaning |
|---|
| Success | The crawler can fetch and parse the page. Check the extracted fields to verify content is being captured correctly. |
| Blocked by robots.txt | The page is disallowed in robots.txt. Update robots.txt or configure the crawler to ignore it. |
| HTTP error (4xx/5xx) | The page returned an error. Verify the URL is accessible in a browser. |
| No content extracted | The page loaded but no indexable content was found. The content may require JavaScript rendering or may be in elements the crawler doesn’t extract. |
| Excluded by crawler rules | The URL matches an exclusion pattern in your crawler configuration. Review your include/exclude rules. |
| Redirect | The URL redirects to another page. Consider using the final URL instead. |
- JavaScript-rendered content: If your page content loads via JavaScript. Ask Cludo Support or Account Manager to enable JavaScript rendering in crawler settings
- Login-protected pages: The crawler cannot access pages behind authentication
- Slow-loading pages: Pages that take too long to load may time out
- Missing Crawler Fields: Verify the page has title and description for the crawler to extract
Analytics Not Showing Data
Symptom: The analytics dashboard shows no data even though searches are happening.
Fix: Add the Cludo API analytics script or send tracking events through the API. If you build your own search UI, record both query events and result click events so analytics can connect searches to user behavior.
Rate Limiting
Symptom: API returns 429 Too Many Requests.
Fix: Reduce your request rate. If you need higher limits, contact support@cludo.com.
CORS Errors
Symptom: Browser console shows CORS errors when calling the API from client-side code.
Fix: Browser-based integrations should use SiteKey for search-related endpoints or anonymous requests for tracking. Do not expose Basic API keys in client-side code. If you see CORS errors:
- Verify you’re using SiteKey auth (not Basic) for client-side calls
- Ensure the
Authorization header is correctly formatted
- Check that you’re hitting the correct base URL for your region
- Move server-only calls, such as index management and search tools, behind your own backend
Still stuck?
If none of the above resolves your issue:
- Check the FAQ for answers to common questions
- Email support@cludo.com with:
- Your customer ID and engine ID
- The endpoint you’re calling
- The full request (headers + body)
- The full response (status code + body)
