Designing Consistent API Return Codes: Lessons from HTTP Status Codes

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

Many teams suffer from chaotic return‑code definitions: some APIs use integers, others strings; success may be indicated by 0, 1, or even the literal "true", leading to confusion and extra debugging effort.

A disciplined return‑code design, similar to HTTP status codes, can lower communication costs and simplify code maintenance.

HTTP Status Code Reference

HTTP status codes are divided into ranges to make their meaning explicit. For backend developers the most common groups are:

2XX – success (e.g., 200 OK)

5XX – server errors (e.g., 502 Bad Gateway)

Using such segmentation helps quickly infer the cause of a problem.

Parameter Conventions

A return code alone is insufficient; it must be paired with a human‑readable message that explains the situation.

Following the HTTP‑style segmentation, we can split error codes into distinct ranges, making both programs and developers able to differentiate API results easily.

Personalized Messages

While messages are primarily for engineers, different user‑facing scenarios may require distinct wording. For example, error codes 20000‑29999 could indicate order‑creation failures:

20001 – Order creation failed: an order is already in progress.

20002 – Order creation failed: the previous order is queued for creation.

For end‑users, these might be translated to a friendly notice such as "Sorry, you have an ongoing order; please check your order list." The API must still return precise technical information, while the caller translates it for the user.

We can store translated messages in a database and cache them in Redis or locally on the API server.

During response construction, the system matches application_id + code to replace the generic message with the appropriate localized version, allowing mobile apps, WeChat mini‑programs, and web portals to display different texts.

Unified Handling of Return Information

With a standardized code set, tools like Nginx or APM can aggregate request counts per code, enabling alerts (e.g., when code 99999 spikes) and visualizing distribution via pie charts to spot systemic or business‑logic issues.

In summary, a thoughtful return‑code design improves communication efficiency, reduces maintenance overhead, and provides valuable metrics for monitoring backend services.