​
Troubleshooting Guide: Unexpected R2R API Responses

When working with the R2R API, you might encounter responses that don’t match your expectations. This guide will help you diagnose and resolve common issues related to unexpected API behavior.

​
1. Verify API Endpoint and Request

First, ensure you’re using the correct API endpoint and making the proper request.

​
1.1 Check API URL

  • Confirm you’re using the correct base URL for your R2R instance.
  • Verify the endpoint path is correct (e.g., /v2/search for search requests).

​
1.2 Review Request Method

  • Ensure you’re using the appropriate HTTP method (GET, POST, PUT, DELETE) for the endpoint.

​
1.3 Validate Request Headers

  • Check that you’ve included all required headers, especially:
    • Content-Type: application/json for POST requests
    • Authorization header if required

​
1.4 Inspect Request Body

  • For POST requests, verify the JSON structure of your request body.
  • Ensure all required fields are present and correctly formatted.

​
2. Common Unexpected Responses

​
2.1 Empty Results

Symptom: API returns an empty list or no results when you expect data.

Possible Causes:

  • No matching data in the database
  • Incorrect search parameters
  • Issues with data ingestion

Troubleshooting Steps:

  1. Verify your search query or filter parameters.
  2. Check if the data you’re expecting has been successfully ingested.
  3. Try a broader search to see if any results are returned.

​
2.2 Incorrect Data Format

Symptom: API returns data in an unexpected format or structure.

Possible Causes:

  • Changes in API version
  • Misconfiguration in R2R settings

Troubleshooting Steps:

  1. Check the API documentation for the correct response format.
  2. Verify you’re using the latest version of the API.
  3. Review your R2R configuration settings.

​
2.3 Unexpected Error Responses

Symptom: API returns error codes or messages you don’t expect.

Possible Causes:

  • Server-side issues
  • Rate limiting
  • Authorization problems

Troubleshooting Steps:

  1. Check the error message for specific details.
  2. Verify your API key or authentication token.
  3. Ensure you’re not exceeding rate limits.
  4. Check R2R server logs for more information.

​
3. Debugging Techniques

​
3.1 Use Verbose Logging

Enable verbose logging in your API requests to get more detailed information:

import requests

response = requests.get('http://your-r2r-api-url/v2/endpoint',
                        params={'verbose': True})
print(response.json())

​
3.2 Check R2R Server Logs

Access the R2R server logs to look for any error messages or warnings:

docker logs r2r-container-name

​
3.3 Use API Testing Tools

Utilize tools like Postman or cURL to isolate API issues:

curl -X GET "http://your-r2r-api-url/v2/health" -H "accept: application/json"

​
4. Common Issues and Solutions

​
4.1 Inconsistent Search Results

Issue: Search results vary unexpectedly between requests.

Solution:

  • Check if your data is being updated concurrently.
  • Verify the consistency of your vector database (Postgres+pgvector).
  • Ensure your search parameters are consistent.

​
4.2 Slow API Response Times

Issue: API requests take longer than expected to return results.

Solution:

  • Check the size of your dataset and consider optimization.
  • Verify the performance of your database queries.
  • Consider scaling your R2R deployment if dealing with large datasets.

​
4.3 Unexpected Data Relationships

Issue: API returns relationships between data that don’t match expectations.

Solution:

  • Review your knowledge graph structure.
  • Check the logic in your data ingestion and relationship creation processes.
  • Verify that your query is correctly traversing the graph.

​
5. When to Seek Further Help

If you’ve gone through this guide and are still experiencing issues:

  1. Gather all relevant information:

    • API request details (endpoint, method, headers, body)
    • Full response (including headers and body)
    • R2R server logs
    • Any error messages or unexpected behavior

  2. Check the R2R documentation and community forums for similar issues.

  3. If the problem persists, consider reaching out to the R2R community or support channels:

    • Post a detailed question on the R2R GitHub repository
    • Join the R2R Discord community for real-time assistance
    • Contact R2R support if you have a support agreement

Remember to always provide as much context as possible when seeking help, including your R2R version, deployment method, and steps to reproduce the issue.

By following this guide, you should be able to diagnose and resolve most unexpected API response issues in your R2R deployment. If you encounter persistent problems, don’t hesitate to seek help from the R2R community or support channels.