Watch three signals
Most integration problems show up in one of three numbers. Track all three per application, per API:
| Signal | What it tells you | Where to find it |
|---|---|---|
| Request volume | Sudden spikes or drops usually mean a deploy went sideways | Your own metrics or gateway analytics |
| Error rate | A rising 4xx or 5xx share is the first sign of a broken integration | Your own metrics, grouped by status code |
| Latency | Tail (p95, p99) latency matters more than the average | Your own metrics, measured end to end |
Log what you need to debug
For every request, log the outcome and the identifier that ties it back to us:
{
"method": "POST",
"path": "/v1/orders",
"status": 422,
"request_id": "req_8k3j2l",
"duration_ms": 143
}
Include the request_id whenever you contact support. It lets the team find the exact request in seconds instead of guessing from timestamps.
Set alerts before you need them
Alert on the signals that predict trouble, not just on outages:
- Error rate above a threshold you'd consider an incident, such as more than
1%of5xxresponses over five minutes. 429responses at all. Any rate limiting means your traffic pattern needs attention. See Rate limits.401spikes right after a deploy. They usually mean a credential didn't make it into the new environment.- Latency on your
p95, not your average. Averages hide the tail that users feel.
Retries multiply load exactly when the API is struggling. Use exponential backoff with jitter, and only retry the statuses that are safe to retry. See Errors.
Read rate limit headers continuously
Every response includes X-RateLimit-Remaining and X-RateLimit-Reset. Emit them as metrics so you can see quota burn before you hit a 429, and so a new deploy's traffic pattern is visible immediately.
Rehearse the failure path
A monitor nobody has responded to is a fire drill waiting to happen. Once per quarter:
- Force a
429in a staging application by exceeding the rate limit. - Confirm your backoff and retry behavior behaves as designed.
- Confirm the alert fired and the runbook pointed someone in the right direction.