API Error Object

Overview

Meaning and scope

API Error Object is the structured response body that communicates machine-readable details about an API failure. It is used to let clients classify, display, log, and act on errors consistently. It differs from the HTTP status code, which provides a broad transport-level category but usually not enough application detail.

Mechanism and operation

The object includes a stable code, safe message, field-level details, request identifier, and optional retry or documentation information. The API Error Object owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate. Testing API Error Object should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes. Important failure modes include unstable codes, localized parsing, stack traces, sensitive values, excessive nesting, and inconsistent shapes force brittle client logic. Operational evidence should include error code, HTTP status, request ID, field path, retry flag, documentation reference, and schema version.

Practical payment example

A failed payout response carries a structured error code and correlation identifier without exposing secrets in the message.

Operational checks

API Error Object should be documented alongside API Error, API Response Envelope, and API Schema. Changes to API Error Object should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions. Observability for API Error Object should record operation, version, principal, request ID, latency, retry count, error code, and final state without exposing secrets.

Distinctions and limits

A successful transport result from API Error Object should not be interpreted beyond the exact API state documented by the provider.

Related reading

Related definitions: API Error, API Response Envelope.