Designing Clear API Error Codes: Lessons from HTTP Status Practices

1. Introduction

When a client calls an API, developers rely on return codes to determine whether the response meets expectations and how to handle the payload.

Many developers have suffered from inconsistent return code definitions: some APIs use integers, others strings; success may be represented by 0, 1, or "true", leading to confusion.

Thoughtful API return code design reduces communication overhead and maintenance cost.

2. HTTP Status Code Reference

Using HTTP status codes as an example, the status space is divided into ranges to clarify meaning.

For backend developers the common ranges are:

2XX – e.g., 200 → request succeeded.

5XX – e.g., 502 → server error, usually service not running or code exception.

These status codes allow quick diagnosis; the design philosophy is worth emulating.

3. Parameter Convention

Beyond a numeric code, a corresponding message should be provided so humans can understand the result.

Following the HTTP approach, error codes can be segmented, for example:

This uniform design lets both programs and people easily distinguish API outcomes.

4. Personalized Message

Messages are typically written for engineers, but different scenarios may require user‑facing messages.

Example: codes 20000‑29999 indicate order creation failures.

20001 – order creation failed, an order is already in progress.

20002 – order creation failed, a previous order is queued.

For end users the message might be simplified to a polite apology and instruction, while the API still returns the precise code. The translation can be performed by the caller, but providing a personalized message capability in the API is preferable.

The translation mappings can be stored in a database and cached in Redis or locally.

When the request finishes, the system matches application_id+code to replace the message accordingly.

This enables different messages for mobile apps, WeChat mini‑programs, or web order portals.

5. Unified Handling of Return Information

With a unified code set, Nginx or APM tools can aggregate API request code counts and distribution.

Thresholds on the number of a specific code (e.g., 99999) can trigger API anomaly alerts.

Code distribution pie charts help identify system or business process issues.

In summary, a well‑designed return code scheme improves communication efficiency and lowers code maintenance costs.