​

Troubleshooting Guide

​

Authentication Issues

​

401 Unauthorized

{"error": "Invalid API key", "code": "invalid_api_key"}

• Wrong API key
• Missing “Bearer” prefix
• Key has been revoked
• Extra whitespace in header

# ✅ Correct
Authorization: Bearer fltr_sk_abc123...

# ❌ Wrong - missing Bearer
Authorization: fltr_sk_abc123...

# ❌ Wrong - extra colon
Authorization: Bearer: fltr_sk_abc123...

​

403 Forbidden

{"error": "Insufficient permissions", "code": "insufficient_scope"}

• OAuth scope doesn’t include required permission
• Accessing another user’s resources

• Check OAuth scopes
• Verify resource ownership
• Use correct authentication method

​

Search Issues

​

No Results Returned

• Document still processing
• No matching content
• Wrong dataset ID
• Overly specific filters

1. Wait for processing:
   Copy

   # Check document status
   GET /v1/datasets/{dataset_id}/documents/{document_id}
   

2. Try broader queries:
   Copy

   # Instead of
   "query": "exact phrase match"
   
   # Try
   "query": "main keywords"
   

3. Verify dataset:
   Copy

   GET /v1/datasets/{dataset_id}
   

4. Remove filters:
   Copy

   {
     "query": "search term",
     "dataset_id": "ds_abc123"
     // Remove filters temporarily
   }
   

​

Low Relevance Scores

• Poor quality embeddings
• Mismatched terminology
• Short content chunks

1. Enable reranking:
   Copy

   {
     "query": "search term",
     "dataset_id": "ds_abc123",
     "rerank": true  // Improves quality
   }
   

2. Add metadata:
   Copy

   {
     "content": "...",
     "metadata": {
       "title": "Descriptive title",
       "category": "relevant-category",
       "tags": ["keyword1", "keyword2"]
     }
   }
   

3. Improve chunking:
   • Keep related content together
   • Add context to chunks
   • Use descriptive titles

​

Upload Issues

​

413 Payload Too Large

{"error": "Document exceeds maximum size of 10MB"}

1. Split large files:
   Copy

   # Split PDF into sections
   from PyPDF2 import PdfReader, PdfWriter
   
   reader = PdfReader('large.pdf')
   for i in range(0, len(reader.pages), 50):
       writer = PdfWriter()
       for page in reader.pages[i:i+50]:
           writer.add_page(page)
   
       with open(f'section_{i}.pdf', 'wb') as f:
           writer.write(f)
   

2. Compress files:
   Copy

   # Compress images in PDF
   gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 \
      -dPDFSETTINGS=/ebook -dNOPAUSE -dQUIET -dBATCH \
      -sOutputFile=compressed.pdf input.pdf
   

3. Extract text first:
   Copy

   # Upload text instead of file
   with open('large.txt') as f:
       content = f.read()
   
   response = requests.post(
       url,
       json={"content": content}
   )
   

​

Processing Failed

{
  "event": "document.processing_failed",
  "data": {
    "error": {
      "code": "invalid_pdf",
      "message": "PDF is encrypted"
    }
  }
}

1. Remove PDF encryption:
   Copy

   qpdf --decrypt input.pdf output.pdf
   

2. Convert format:
   Copy

   # DOCX to PDF
   libreoffice --headless --convert-to pdf document.docx
   
   # Image to text (OCR)
   tesseract image.png output -l eng
   

3. Repair corrupted PDF: Use online tools or pdftk:
   Copy

   pdftk broken.pdf output fixed.pdf
   

​

Rate Limit Issues

​

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "retry_after": 3600
}

1. Implement backoff:
   Copy

   import time
   
   def make_request():
       response = requests.post(url, headers=headers, json=data)
   
       if response.status_code == 429:
           retry_after = int(response.headers.get('Retry-After', 60))
           time.sleep(retry_after)
           return make_request()  # Retry
   
       return response
   

2. Use batch endpoints:
   Copy

   # Instead of
   for query in queries:
       results.append(query_dataset(query))  # Multiple requests
   
   # Use
   results = batch_query_dataset(queries)  # Single request
   

3. Cache results:
   Copy

   from functools import lru_cache
   
   @lru_cache(maxsize=100)
   def cached_query(query):
       return query_dataset(query)
   

4. Upgrade authentication:
   • API Key: 1,000/hour
   • OAuth: 15,000/hour (15x more!)

​

Network Issues

​

Connection Timeout

• Network connectivity issues
• Firewall blocking requests
• DNS resolution failure

1. Check connectivity:
   Copy

   # Test API is reachable
   curl -I https://api.fltr.com/v1/datasets
   
   # Check DNS
   nslookup api.fltr.com
   

2. Increase timeout:
   Copy

   response = requests.post(
       url,
       headers=headers,
       json=data,
       timeout=30  # 30 second timeout
   )
   

3. Check firewall:
   • Allow outbound HTTPS (port 443)
   • Whitelist api.fltr.com

​

SSL/TLS Errors

SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

1. Update CA certificates:
   Copy

   # macOS
   pip install --upgrade certifi
   
   # Ubuntu
   sudo apt-get update && sudo apt-get install --reinstall ca-certificates
   

2. Verify TLS version:
   Copy

   import ssl
   print(ssl.OPENSSL_VERSION)  # Should be 1.1.1 or higher
   

​

Integration Issues

​

Zapier Not Receiving Data

• Wrong field paths
• Response not parsed
• Timeout

1. Check raw output:
   • Click on Zapier step
   • View “Raw Output” tab
   • Verify data structure
2. Use correct paths:
   Copy

   # Not this
   results.0.content
   
   # Use this (double underscore)
   results__0__content
   

3. Test webhook:
   • Send test request
   • Check Zapier task history
   • Verify headers

​

Make.com Mapping Issues

• Array iteration problem
• Missing data

1. Use Iterator:
   • Add Iterator module
   • Connect to {{http.data.results}}
   • Process each result
2. Map correctly:
   Copy

   {{map(2.data.results; "content")}}
   {{2.data.results[1].metadata.title}}
   

​

Getting Help

​

Debug Checklist

• Check API status at status.fltr.com
• Verify API key is correct and active
• Check rate limit headers
• Review error message and code
• Test with cURL to isolate issue
• Check request/response logs
• Verify dataset/document IDs exist
• Try simple request first
• Check for network/firewall issues
• Review recent code changes