Debug API load tests

Troubleshoot and optimize API load tests using error analysis, response time metrics, and framework-specific debugging.

This guide walks you through systematic debugging approaches for common API load test failures. Use the triage questions and targeted sections below to identify root causes and optimize your tests.

30-second triage

Start with these four questions to identify the issue:

Debug high error rates

High error rates indicate failed API requests or test execution issues.

Steps:

1. Check the Errors tab in results to identify error type and frequency.
2. Group errors by HTTP status code:
   • 4xx errors: Client-side issues (malformed request, missing data, authentication failure).
   • 5xx errors: Server-side issues (application error, overload, dependency failure).
   • Connection errors: Network timeouts or refused connections.
3. Review the Requests tab for:
   • Which endpoints have the most failures.
   • Failure pattern (all requests or specific endpoints).
   • Request and response payloads for failed calls.
4. Check if errors spike when load increases.
5. Compare error distribution across Virtual Users (VUs).

By HTTP status code:

Identify the specific status code and take the recommended action:

Common causes:

• Malformed request body or missing required fields
• Expired or invalid authentication tokens
• API rate limits or throttling at high VU levels
• Backend service under load or unavailable
• Network connectivity issues

Debug slow response times

Slow response times impact application performance and user experience.

Steps:

1. Check the Response Time metric in Summary tab (p50, p95, p99 percentiles).
2. Review the Requests tab for:
   • Slowest endpoints.
   • Response time distribution across requests.
   • Correlation between request type and response time.
3. Check if slowness correlates with VU increase (indicate server bottleneck).
4. Compare response times across load zones for regional differences.
5. Identify if specific endpoints are consistently slow.

Common causes:

• Backend service under load
• Slow database queries
• External service latency (third-party APIs)
• Network latency in load zone
• Large response payloads
• Unoptimized query or business logic

Optimization strategies:

• Add caching to reduce database load
• Optimize slow database queries
• Implement request batching to reduce API calls
• Use connection pooling (k6, JMeter) for efficient connection reuse

Debug low throughput

Low throughput indicates fewer requests per second than expected.

Steps:

1. Check Summary tab for requests per second (RPS) metric
2. Calculate expected throughput: (VUs × iterations) / duration
3. Compare actual vs. expected throughput
4. Check if throughput increases with VU increase (proper scaling)
5. Identify if specific endpoints have low throughput

Common causes:

• High think time or delays between requests
• Large connection pool size with limited connections
• Low iteration count or test duration
• Network latency affecting request speed
• Backend throttling or rate limiting

Optimization strategies:

• Reduce think time for rapid-fire testing
• Increase connection pool size (verify backend can handle)
• Increase VU count or test duration
• Use HTTP/2 or connection keep-alive for efficiency
• Batch multiple requests into single API call when possible

Debug framework-specific issues

Framework configuration directly impacts test execution.

k6 configuration:

• Batch settings: Use batch() function to send multiple requests in parallel
• Connection pooling: Verify http client is reused across VUs
• Think time: Check sleep() duration between requests
• Thresholds: Ensure threshold definitions are correct

JMeter configuration:

• Thread pool: Verify thread count matches VU configuration
• Connection managers: Check HTTP Request Defaults are configured
• Listeners: Review Sample Result listeners for detailed request/response data
• Assertions: Identify if assertions are too strict, causing false failures

Common issues:

• k6: Incorrect __VU or __ITER variable usage
• JMeter: Missing HTTP Request Defaults or improper thread group setup
• Both: Hardcoded delays or think time too high
• Both: Connection pooling not configured, causing connection reuse issues

Debug infrastructure health

Infrastructure issues affect test execution quality.

Steps:

1. Check Engine Health tab for:
   • CPU usage (target: < 80%)
   • Memory usage (target: < 90%)
   • Network I/O (monitor for packet loss or latency)
2. Identify if resource exhaustion correlates with test issues
3. Compare health metrics across load zones
4. Check for connection limit exhaustion

Common causes:

• Too many concurrent VUs for available resources
• Memory leaks in test framework or scripts
• Insufficient connection pool size causing wait times
• Network bandwidth saturation

Debug threshold breaches

Thresholds define acceptable performance limits.

Steps:

1. Identify which threshold was exceeded
2. Compare the metric value against the defined threshold
3. Check if breach is consistent or occasional
4. Review timeseries to see when breach started
5. Analyze if threshold is appropriate for application SLA

Common thresholds:

• Error rate: target < 1%
• Response time p95: depends on API SLA
• Throughput: target matches expected RPS
• Connection errors: target 0

Regression analysis

Compare current test against baseline to identify performance degradation.

Steps:

1. Use Compare Execution feature to select current and baseline runs
2. Compare metrics side-by-side for errors, response time, throughput
3. Identify which metrics degraded significantly
4. Check git history or deployment logs for changes between runs
5. Isolate the change that caused regression

Common pitfalls

Avoid these common mistakes that lead to test failures or inaccurate results:

Next steps

• For unresolved issues, contact our technical support team with test execution IDs and request/response logs
• Review Load Testing FAQs for general questions
• Check the Troubleshooting guide for additional debugging techniques