What is API Error Handling?

API error handling communicates failed requests to client applications in a consistent, understandable, and safe format. An error response should not merely say that something went wrong; the client should know what failed, whether retrying makes sense, and what message can be shown to the user.

A good error response includes the right HTTP status code, a machine-readable error code, a developer-friendly message, and field-level validation details when relevant. Production APIs should not expose stack traces, SQL queries, or secret configuration values.

Common Design Choices

400 for validation, 401 for authentication, 403 for authorization, 404 for not found, and 409 for conflicts
429 for rate limits, often with a Retry-After header
5xx responses to signal a server-side failure rather than a client mistake
Correlation IDs to make the related request easy to find in logs

Business Use

If HTTP status codes are chosen poorly, client apps may retry unnecessarily or show the wrong message. In REST API design, standardizing the error format early lets mobile, web, and partner teams rely on the same behavior.

Error handling also affects customer experience. Payment failure, out-of-stock state, and permission denial should not all return the same generic message, because support teams and users need different next steps.