API Error

Overview

What it means

An API error is a structured response or transport failure indicating that an API request could not be completed as expected. Different errors require different recovery decisions; a generic “retry” button is unsafe for payment-changing operations.

How it works

Clients inspect transport status, HTTP status code, provider error code, message, request ID and idempotency information. Validation or authorization errors usually require correction; rate-limit and transient server errors may warrant bounded backoff; network timeout can leave outcome unknown and requires a state query.

Understanding the technical details

Build an error classification table rather than retrying all non-success responses. For example, bad input must be fixed; expired credentials need secure rotation; rate limits need bounded waiting; and uncertain network failures require a status lookup using the original operation ID. Log provider request IDs and safe diagnostic fields, but never API secrets. Customer messages should reflect actual uncertainty: “processing status unknown” can be more accurate than “payment failed.”

Additional protocol context

Not every unsuccessful business outcome is a system failure, and one generic error hides whether retry, correction, escalation, or reconciliation is appropriate. Excessive stack traces and internal identifiers can disclose sensitive information, while inconsistent errors create brittle client parsing.

Providers should define an error taxonomy, map statuses consistently, separate transient and permanent conditions, and document retry guidance. Clients should branch on stable codes, preserve correlation identifiers, sanitize logs, respect backoff, and reconcile uncertain state when the response does not prove nonexecution.

Common failures and limitations

Never log secret keys or full sensitive payloads alongside errors. Avoid infinite retries and detect schema changes or permanent permission failures. An HTTP 200 can still contain business-level failure information if the API defines that shape.

Related concepts

Webhook, Webhook Verification, Merchant API Key.

Further reading

Stripe — Error handling.