How do I test rate limits and error handling on an API?

To test rate limits and error handling on an API, you want to verify two things:

1. The API enforces limits correctly
2. Your client handles failures gracefully

1) Test rate limits

What to check

• Requests per second/minute/hour limits
• Per-user, per-token, per-IP, per-endpoint limits
• Burst behavior vs sustained traffic
• Reset timing and headers (Retry-After, X-RateLimit-Remaining, etc.)

How to test

• Send repeated requests quickly until the API starts rejecting them.
• Observe the status codes:
  • Usually 429 Too Many Requests
  • Sometimes 403, 503, or custom error codes
• Verify response headers include useful limit info if documented.

Example with curl

for i in {1..100}; do
  curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/resource
done

Better load tools

Use tools like:

• k6
• JMeter
• Locust
• Artillery
• Apache Bench (ab)

These let you control concurrency, ramp-up, and request rate.

What to verify

• The limit is triggered at the expected threshold
• The API returns the documented status code/message
• The Retry-After header is present when appropriate
• Normal traffic resumes after the reset window
• One client/user hitting limits does not affect others unless intended

---

2) Test error handling

Simulate common failures

• 400 Bad Request: send invalid/malformed input
• 401 Unauthorized: use missing/invalid credentials
• 403 Forbidden: use insufficient permissions
• 404 Not Found: request missing resource
• 405 Method Not Allowed: wrong HTTP method
• 409 Conflict: duplicate or conflicting update
• 422 Unprocessable Entity: validation errors
• 500 Internal Server Error: force server-side failure if possible
• 502/503/504: simulate upstream/service/network issues

How to trigger them

• Send bad JSON
• Omit required fields
• Use expired/invalid tokens
• Request invalid endpoints
• Use unsupported methods
• Introduce dependency failures with mocks/stubs
• Kill or delay backend services in staging

Example bad JSON

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"email": "not-an-email"}'

Example missing auth

curl https://api.example.com/protected

What to verify

• Correct HTTP status code
• Clear, non-leaky error message
• Consistent error schema
• No stack traces or sensitive info exposed
• Client can recover or retry appropriately
• Logging/metrics capture the failure

---

3) Test client-side handling

Your API may be fine, but your client should still handle:

• Retries with exponential backoff
• Respecting Retry-After
• Not retrying non-retryable errors like many 4xx
• Timeouts
• Circuit breaker behavior
• Partial failures and idempotency

Example behavior to verify

• On 429, wait and retry later
• On 500, retry only if request is safe/idempotent
• On 400, do not retry; fix input
• On timeouts, retry a limited number of times

---

4) Best practices

• Test in staging, not production
• Coordinate with the team so tests don’t trigger alerts unexpectedly
• Start low and ramp up
• Use unique test credentials/clients
• Monitor logs, metrics, and dashboards during tests
• Confirm limits don’t accidentally lock out legitimate users

---

5) Simple checklist

• Rate limit threshold reached as expected
• 429 returned correctly
• Retry-After/limit headers correct
• Error codes match documentation
• Error payloads are consistent
• Sensitive info is not exposed
• Client retries appropriately
• Services recover after failure/load subsides

If you want, I can also give you:

• a k6 script for rate-limit testing,
• a Postman collection for error cases,
• or a Python test script using requests/pytest.