API Error

Overview

API Error is a failure result indicating that an API request could not be accepted, processed, authorized, or completed as expected. It is used to tell the client what happened and whether correction, retry, or escalation is appropriate. It differs from a transport failure, where no trustworthy API response may have been received.

A typical implementation works as follows: The server returns an HTTP status or protocol code, a stable application code, safe message, field details, and a correlation identifier. Data handled by API Error should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.

Common risks include vague messages and inconsistent codes. Important failure modes include vague messages, inconsistent codes, sensitive data leakage, and classifying permanent errors as retryable. These failures can worsen incidents. Testing API Error should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

Core controls require teams to use a documented error taxonomy, preserve correlation, separate client and server faults, and avoid exposing secrets or internals. For API Error, the application should preserve a correlation path from request construction through response, asynchronous completion, and final business state.

Operational evidence should include status, application code, request ID, endpoint, timestamp, retryability, and sanitized context. API Error should be documented alongside API Error Object, API Error Rate, and Retry Policy.

The API Error owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate. The API Error contract should define identifiers, validation, authorization, status semantics, errors, limits, and version behavior at the same boundary.