Watch three signals

Most integration problems show up in one of three numbers. Track all three per application, per API:

SignalWhat it tells youWhere to find it
Request volumeSudden spikes or drops usually mean a deploy went sidewaysYour own metrics or gateway analytics
Error rateA rising 4xx or 5xx share is the first sign of a broken integrationYour own metrics, grouped by status code
LatencyTail (p95, p99) latency matters more than the averageYour 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% of 5xx responses over five minutes.
  • 429 responses at all. Any rate limiting means your traffic pattern needs attention. See Rate limits.
  • 401 spikes 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.
Retry blindly and you'll alert on yourself

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:

  1. Force a 429 in a staging application by exceeding the rate limit.
  2. Confirm your backoff and retry behavior behaves as designed.
  3. Confirm the alert fired and the runbook pointed someone in the right direction.

Next steps