Troubleshooting

Solutions for common Cludo API errors and integration issues.

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.

Debugging tip: Decode your base64 token to verify its contents:

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:

1. Check your customer ID:

   • Below 10,000,000 → EU: https://api.cludo.com
   • 10,000,000 and above → US: https://api-us1.cludo.com

2. 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:

1. Log in to MyCludo
2. Navigate to Crawlers and select your crawler
3. Click the Test Crawler button
4. 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.

Common issues Test Crawler helps identify:

• 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 [e-mail].

---

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:

1. Verify you’re using SiteKey auth (not Basic) for client-side calls
2. Ensure the Authorization header is correctly formatted
3. Check that you’re hitting the correct base URL for your region
4. 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:

1. Check the FAQ for answers to common questions
2. Email [e-mail] with:
   • Your customer ID and engine ID
   • The endpoint you’re calling
   • The full request (headers + body)
   • The full response (status code + body)