​

Tydli Troubleshooting Guide

​

🚨 Common Issues

​

Credential Issues

• Cause: Invalid or expired API credentials
• Solution:
  1. Go to deployment settings
  2. Click “Test Credentials”
  3. If test fails, update credentials
  4. Re-test until successful
  5. See Authentication Methods for details

• Cause: Different endpoints have different requirements
• Solution:
  1. Check API documentation for endpoint-specific auth
  2. Verify all endpoints in OpenAPI spec use same auth
  3. Test multiple endpoints manually
  4. See Authentication Methods for details

​

File Upload Problems

• Cause: File is not a valid OpenAPI specification
• Solution:
  • Ensure file is JSON or YAML format
  • Verify OpenAPI version is 3.0 or higher
  • Check for syntax errors in the specification
  • Alternative: Use ”✨ Any Format (AI)” tab to upload PDFs, docs, or other formats

• Cause: Network timeout or file too large
• Solution:
  • Check file size (max 10MB for OpenAPI, 5MB for AI processing)
  • Try refreshing the page
  • Use paste method for large specifications

​

AI Document Processing Issues

• Cause: AI couldn’t extract enough structured API information
• Solution:
  • Ensure your docs include clear HTTP endpoints (GET, POST, etc.)
  • Add explicit parameter names and types
  • Specify the base URL of the API
  • Remove marketing content, focus on technical reference
  • → See AI best practices

• Cause: You’ve used your 5 free AI conversions for today
• Solution:
  • Wait until midnight (your local time) for reset
  • Use OpenAPI upload directly if you have a spec (no limit)
  • Convert to OpenAPI manually using Swagger Editor

• Cause: Documentation lacks clear API structure
• Solution:
  • Review the preview to see what was extracted
  • Add missing endpoint details to your documentation
  • Try a different input format (paste vs upload)
  • Provide cleaner, more technical documentation

• Cause: Document is too large or complex
• Solution:
  • Keep files under 5 MB
  • Extract just the API reference section
  • Split large documentation into parts
  • Try pasting key sections instead of uploading

​

Validation Errors

• Solution: Add required OpenAPI fields:
  Copy

  openapi: 3.0.1
  info:
    title: "Your API Title"
    version: "1.0.0"
  

• Solution: Update version in your specification:
  Copy

  openapi: 3.0.1  # or 3.0.2, 3.0.3, etc.
  

​

Deployment Issues

• Cause: Server generation failed
• Solution:
  1. Check deployment logs for error details
  2. Verify OpenAPI specification is valid
  3. Try regenerating the deployment

• Cause: Server not properly deployed or stopped
• Solution:
  1. Check deployment status is “Ready”
  2. Use “Health Check” to verify server is responding
  3. Restart deployment if needed

• Cause: Too many requests in short time period
• Solution: Wait a few minutes before retrying (check your dashboard for rate limit details)

​

Authentication Problems

• Cause: Account email not verified
• Solution:
  1. Check your email inbox for verification link
  2. Click the link to verify your email
  3. Return to the application and log in
  4. If link expired, contact support for new verification email

• Cause: Session expired or invalid
• Solution:
  1. Sign out and sign back in
  2. Refresh the page
  3. Clear browser cache if problems persist

​

Performance Issues

• Cause: Large number of deployments or logs
• Solution:
  • Use deployment filters
  • Clear old deployment logs
  • Refresh the page

• Cause: Large or complex OpenAPI specification
• Solution:
  • Simplify specification if possible
  • Break large APIs into smaller specifications
  • Use URL import instead of file upload

​

🔧 Browser Issues

​

Compatibility

• Supported Browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
• JavaScript Required: Ensure JavaScript is enabled
• Ad Blockers: May interfere with file uploads

​

Cache Issues

1. Clear browser cache and cookies
2. Disable browser extensions temporarily
3. Try incognito/private browsing mode

​

📊 Getting Help

​

Check System Status

• View deployment logs for detailed error information
• Use health check feature to verify server status
• Monitor deployment dashboard for real-time updates

​

Reporting Issues

• Error messages (exact text)
• Browser and version
• Steps to reproduce
• OpenAPI specification (if applicable)

​

Contact Support

• Documentation: Check User Guide
• API Reference: See API Reference
• Status Page: Monitor platform status

​

🔍 Advanced Troubleshooting

​

Deployment Failed or Stuck

​

Check Your OpenAPI Spec

• Ensure valid JSON or YAML format: Use a validator before uploading
• Verify all referenced schemas exist: Check all $ref pointers
• Check for circular references: Avoid schemas that reference themselves
• Test with a simple spec first: Try the Petstore example to isolate issues

​

View Deployment Logs

1. Go to your deployment in the dashboard
2. Click “View Logs” to see detailed error messages
3. Look for validation errors or generation failures

​

Authentication Errors (401/403)

​

Verify Credentials

• Double-check API key, username, or OAuth credentials
• Ensure credentials have not expired
• Test credentials directly with the target API using curl or Postman

# Test API key authentication
curl -H "X-API-Key: YOUR_KEY" https://api.example.com/endpoint

# Test Bearer token
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/endpoint

​

Check Header Format

Authorization: Bearer your-token-here
X-API-Key: your-key-here
Authorization: Basic base64-encoded-credentials

​

OAuth Troubleshooting

• Verify redirect URIs are correctly configured in your OAuth app settings
• Check that requested scopes are allowed for your application
• Ensure token refresh is working (check deployment logs for refresh attempts)
• Confirm client_id and client_secret are correct

​

Claude Can’t Find or Use MCP Server

​

Verify Configuration

1. Check the URL in claude_desktop_config.json is correct and complete
2. Ensure proper JSON formatting (no trailing commas, proper quotes)
3. Verify the auth token is present and correct
4. Confirm you restarted Claude Desktop after config changes (full quit + reopen)

​

Test Server URL

# Test if server is accessible
curl https://your-project.supabase.co/functions/v1/mcp-router/your-slug

# Should return MCP server metadata (not an error)

​

Check Claude Logs

• Mac: ~/Library/Logs/Claude/
• Windows: %APPDATA%\Claude\logs\

​

Rate Limit Errors (429)

​

Check Your Plan Limits

• Free tier: 1,000 requests/month, 20 requests/hour
• Pro tier: 50,000 requests/month, 200 requests/hour
• Enterprise: Custom limits

​

Optimize API Calls

• Batch multiple operations when possible (combine requests)
• Cache responses in your application or Claude’s context
• Use webhooks instead of polling when available
• Implement pagination for large data sets
• Only request necessary fields using field selectors

​

IP Blocked Errors (403)

​

Possible Causes

• Your IP exceeded rate limits multiple times
• Your IP was manually blocked by an administrator
• Suspicious activity was detected from your IP

​

Solutions

1. Wait and retry - Temporary blocks may expire automatically
2. Check your usage patterns - Ensure you’re not making excessive requests
3. Contact support - If you believe the block is in error
4. Use authentication - Authenticated endpoints have different rate limits

​

For API Consumers

• Check your MCP server’s authentication configuration
• Consider implementing user-level authentication instead of public access
• Review your rate limit settings in the dashboard

​

Request Timeouts

​

Check Target API Performance

• Test the target API directly to measure response time
• Some endpoints may naturally take longer (data exports, reports)
• Consider async patterns for long-running operations

​

MCP Timeout Limits

• Break large operations into smaller chunks
• Use pagination for large data sets (e.g., limit to 100 items per request)
• Implement async job patterns with status polling:
  1. Start job → Get job ID
  2. Poll status → Check if complete
  3. Retrieve results → When ready

​

OpenAPI Spec Validation Issues

​

Common Validation Errors

openapi: 3.1.0
info:
  title: "Your API Title"  # Required
  version: "1.0.0"          # Required
paths: {}                    # Required (can't be empty)

# Bad - schema doesn't exist
components:
  schemas:
    User:
      $ref: '#/components/schemas/NonExistentSchema'

# Good - schema exists
components:
  schemas:
    User:
      $ref: '#/components/schemas/Profile'
    Profile:
      type: object

# Bad - creates infinite loop
components:
  schemas:
    A:
      $ref: '#/components/schemas/B'
    B:
      $ref: '#/components/schemas/A'

# Bad
servers:
  - url: not-a-valid-url

# Good
servers:
  - url: https://api.example.com/v1

​

Validation Tools

• JSON: jsonlint.com
• YAML: yamllint.com
• OpenAPI: editor.swagger.io

​

🔍 Advanced Debugging

​

Database Query Debugging

SELECT * FROM deployment_logs
WHERE deployment_id = 'your-deployment-id'
AND status = 'failure'
ORDER BY created_at DESC
LIMIT 20;

SELECT
  path,
  AVG(response_time_ms) as avg_ms,
  MAX(response_time_ms) as max_ms,
  COUNT(*) as request_count
FROM request_usage_tracking
WHERE deployment_id = 'your-deployment-id'
  AND response_time_ms IS NOT NULL
GROUP BY path
ORDER BY avg_ms DESC
LIMIT 10;

SELECT * FROM deployment_logs
WHERE deployment_id = 'your-deployment-id'
  AND operation = 'authentication'
  AND status = 'failure'
ORDER BY created_at DESC;

SELECT
  DATE_TRUNC('hour', created_at) as hour,
  status,
  COUNT(*) as count
FROM deployment_logs
WHERE deployment_id = 'your-deployment-id'
  AND created_at > NOW() - INTERVAL '24 hours'
GROUP BY hour, status
ORDER BY hour DESC;

SELECT
  path,
  response_status,
  COUNT(*) as error_count
FROM request_usage_tracking
WHERE deployment_id = 'your-deployment-id'
  AND response_status >= 400
GROUP BY path, response_status
ORDER BY error_count DESC;

​

Development Mode

1. Open browser developer tools (F12)
2. Check Console tab for JavaScript errors
3. Monitor Network tab for failed requests
4. Check Application tab for local storage issues

​

API Debugging

• Test MCP endpoints directly using curl
• Verify JWT tokens are valid
• Check CORS headers for cross-origin issues

​

📚 Additional Resources

• FAQ: Frequently asked questions
• Getting Help: How to get support
• Best Practices: Avoid common pitfalls
• Authentication Methods: Auth troubleshooting