API Error Rate

Overview

API Error Rate is the proportion of API requests that result in defined error outcomes during a stated period and population. It is used to measure reliability, detect incidents, and compare behavior across endpoints or releases. It differs from raw error count, which does not account for request volume.

A typical implementation works as follows: Monitoring divides qualifying errors by eligible requests and segments the result by endpoint, status class, client, region, and cause. A successful transport result from API Error Rate should not be interpreted beyond the exact API state documented by the provider.

Common risks include counting expected validation failures and retries as equivalent errors. Important failure modes include including expected validation failures, retries, health checks, or client cancellations without definition. These failures can produce misleading alerts.

Core controls require teams to publish numerator and denominator rules, separate client and server errors, deduplicate retries where needed, set volume thresholds, and correlate with latency. The API Error Rate owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

Operational evidence should include time window, request count, error count, error classes, endpoint, client, release, and sampling method. API Error Rate should be documented alongside API Error, API Monitoring, and API Performance. The API Error Rate contract should define identifiers, validation, authorization, status semantics, errors, limits, and version behavior at the same boundary.

Changes to API Error Rate should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions.