9. Troubleshooting

This section provides guidance on identifying and resolving common issues encountered while using the Ferdy Framework. It covers errors during setup, API interactions, integrations, and runtime issues.

9.1 Common Issues and Solutions

1. Authentication Errors

  • Problem: 401 Unauthorized or 403 Forbidden.

  • Cause:

    1. Invalid API key or access token.

    2. Expired access token.

    3. Missing Authorization header.

  • Solution:

    1. Verify that the API key or OAuth token is correct.

    2. Check if the token has expired and refresh it using the /auth/token endpoint.

Ensure that the Authorization header includes the correct token format: Authorization: Bearer YOUR_API_KEY

2. API Errors

  • Problem: 400 Bad Request.

  • Cause:

    1. Incorrect request parameters.

    2. Malformed JSON body.

  • Solution:

    1. Validate the request body against the API documentation.

    2. Use tools like Postman to test the API with correct parameters.

Check the API response for a detailed error message in the error object: {

"error": {

"code": 400,

"message": "Invalid input format."

}

}

3. Slow API Responses

  • Problem: API requests take longer than expected.

  • Cause:

    1. Network latency.

    2. Overloaded servers during peak usage.

  • Solution:

    1. Test the API endpoint's latency using a tool like curl or Postman.

    2. Enable caching for static data or frequently accessed results.

    3. Contact Ferdy support if latency persists across all endpoints.

4. Voice Recognition Fails

  • Problem: The system does not recognize or process voice inputs.

  • Cause:

    1. Microphone permissions are disabled.

    2. Poor audio quality or background noise.

  • Solution:

    1. Check and enable microphone permissions in the browser or app settings.

    2. Ensure the audio input is clear and free of background noise.

    3. Test the ASR (Automatic Speech Recognition) service independently.

5. Task Execution Issues

  • Problem: Task creation or execution fails (500 Internal Server Error).

  • Cause:

    1. Workflow misconfiguration.

    2. Third-party API integration failure.

  • Solution:

    1. Validate workflow configuration by testing individual steps.

    2. Check third-party service availability (e.g., Google Calendar API status).

    3. Review the server logs for detailed error information.

6. Missing or Incorrect Responses

  • Problem: Ferdy returns incomplete or irrelevant responses.

  • Cause:

    1. Knowledge base misalignment.

    2. Incorrect user context provided.

  • Solution:

    1. Update the knowledge base with relevant, accurate data.

    2. Pass detailed context (e.g., location, preferences) in the API request.

Enable debug mode to inspect response generation: {

"debug_info": {

"intent": "weather_query",

"confidence": 0.92

}

}

9.2 Debugging Tools

  1. Enable Ferdy Debug Mode

    • Add debug: true to your SDK or API configuration to log detailed information about errors, responses, and workflows.

  2. Use Developer Tools

    • Postman: Test and debug API endpoints interactively.

cURL: Validate HTTP requests and check response times: curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -d '{"input": "Hello"}' https://api.ferdy.ai/converse

  1. Monitor Logs

    • Check Ferdy API logs via the Developer Portal for detailed traces of failed requests.

    • Access local server logs (for on-prem deployments).

9.3 Diagnostic Checklist

  1. Network Connectivity

    • Ensure stable internet connectivity for API requests.

    • Test DNS resolution for api.ferdy.ai.

  2. API Configuration

    • Verify the API base URL and endpoints are correct.

    • Check for any version mismatch in the API URL (e.g., /v1 vs. /v2).

  3. Third-Party Integrations

    • Test external APIs independently to ensure availability.

    • Verify OAuth credentials for connected services.

  4. SDK/Plugin Updates

    • Ensure you’re using the latest SDK or plugin version to avoid compatibility issues.

9.4 Reporting Issues

If the above solutions do not resolve the issue, report it to the Ferdy support team with the following details:

  1. Issue Summary: A brief description of the problem.

  2. Steps to Reproduce: A step-by-step guide to replicate the issue.

  3. Request Details:

    • Endpoint, request body, and headers (excluding sensitive information).

    • Timestamp of the issue.

  4. Error Logs:

    • API response and any server-side logs.

9.5 Contacting Support

  • Email: support@feeda.com

  • Live Chat: Available in the Ferdy Developer Portal.

  • Support Hours: 24/7 for enterprise users, 9 AM - 6 PM (local time) for free-tier users.

  • Community Forum: Access the Ferdy developer community to discuss issues and solutions.

Previous8. Best PracticesNext10. FAQs

Last updated