Articles on: General

Reporting Issues: How to Provide Effective Context

Before contacting our support team about a potential API issue, it's important to first confirm that the problem is specifically with our API rather than with your implementation or other systems. Once you've determined that our API is the source of the issue, providing proper context is essential for our support team to efficiently diagnose and address your concerns.


Verify It's an API Issue First


Our support team is dedicated to resolving issues with our API service, but we're not in a position to troubleshoot general implementation problems or issues with your application. Before submitting a support request, please:


  1. Verify the issue is reproducible with direct API calls (using tools like Postman or cURL) outside of your application
  2. Review our documentation to ensure your implementation follows our recommended practices


Once you've confirmed the issue is specifically with our API, please provide comprehensive details as outlined below.


Why We Need Proper Context


API issues can originate from multiple sources:


  1. API Service Issues: Problems with our servers, rate limiting, or service outages
  2. Network Issues: Connectivity problems between your systems and our API
  3. Implementation Issues: How your code interacts with our API, including improper error handling, inefficient request patterns, or missing parameters
  4. Client-Side Issues: Browser limitations, frontend rendering bottlenecks, or client hardware constraints


Without detailed context, our support team must make assumptions that can lead to:


  • Wasted time investigating unrelated systems
  • Back-and-forth communications that delay resolution
  • Frustration on both sides when suggestions don't resolve the issue
  • Inability to identify patterns that might affect other users


Insufficient vs. Sufficient Context Examples


❌ Insufficient Context


"Our website is running very slow. Can you tell us what might be causing this?"


This report lacks specific details that would allow us to begin troubleshooting, such as:


  • Which API endpoints are affected
  • Request parameters being used
  • Response times and error messages
  • When the issue started occurring
  • Whether it happens consistently or intermittently


✅ Sufficient Context


"Since Monday (March 2), we've been experiencing slow response times (>5 seconds) when calling the /listings endpoint with date ranges exceeding 30 days. Previously, these requests completed in under 1 second.
Here's an example request:
GET /listings?minListDate=2024-01-01
Headers: repliers-api-key: DFSDFAD325232432...
The response eventually returns with status 200, but takes 5-8 seconds to complete. Our application logs show no network timeouts, and other API endpoints are performing normally.
We've tested from multiple networks and devices with the same result. "


This report provides:


  • Specific endpoint experiencing issues
  • Exact request parameters
  • When the problem started
  • Expected vs. actual performance
  • Testing steps already taken
  • Supporting evidence (logs, screenshots, video captures)


What to Include in Your Support Request


For fastest resolution, please include:


1. Request Details


  • Complete URL with all query parameters (remember to sanitize sensitive data)
  • HTTP method (GET, POST, etc.)
  • Request headers
  • Request body (for POST/PUT requests)


2. Response Information


  • HTTP status code
  • Response time
  • Response headers
  • Response body (or description if too large)
  • Any error messages or codes


3. Pattern Information


  • When did the issue start?
  • Is it consistent or intermittent?


4. Supporting Evidence


  • Screenshots of errors
  • Code snippets showing your implementation
  • Performance logs or metrics
  • Network request timelines
  • Video captures


Tools for Capturing API Context


These tools can help you capture detailed request/response information:


  • Browser DevTools: Network tab provides detailed timing and request/response information
  • Postman: Create and test API requests independent of your application
  • cURL: Command-line requests that can be shared directly with support
  • API Monitoring Tools: New Relic, Datadog, or similar tools that track API performance
  • Screen Recording Tools: Loom, ScreenPal, ShareX


Next Steps


When you submit a support ticket with comprehensive context:


  1. Our team can immediately begin investigating the specific issue
  2. We can compare your experience with system-wide metrics
  3. We can provide targeted recommendations for resolution
  4. If needed, we can route your issue to specialized team members


Remember, detailed context helps us help you faster. Even if you believe the issue is on our end, providing implementation details eliminates variables and speeds up resolution time for everyone.

Updated on: 04/03/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!