Designing API Error Codes and Messages: Best Practices

1. Introduction

When a client calls an API, the response code is used to determine whether the result meets expectations and how to handle the returned data. In practice, many developers have suffered from chaotic error‑code definitions: some APIs use integers, others strings; success may be indicated by 0, 1, or even the literal "true". Such inconsistency leads to headaches.

Designing API return codes carefully is essential because a good scheme lowers communication overhead and reduces code‑maintenance costs.

2. HTTP Status Code Reference

Using HTTP status codes as a model, the codes are divided into ranges to make their meaning explicit. For backend developers the most common ranges are:

2XX – success (e.g., 200 means request succeeded)

5XX – server error (e.g., 502 indicates a server exception or service not running)

This segmentation helps quickly infer the cause of a problem and is worth emulating for custom API codes.

3. Parameter Convention

Only a numeric code is insufficient; each code should be accompanied by a human‑readable message so that developers can understand the issue. The article also mentions a promotional note about a surprise gift, which is unrelated to the technical content.

Following the HTTP‑style segmentation, custom error codes are grouped into ranges, as illustrated by the diagrams in the original article.

4. Personalized Message

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

20001 – order creation failed because an order is already in progress

20002 – order creation failed because a previous order is still being queued

For end users the message could be simplified to: "Sorry, you have an ongoing order; please check your order list." The API should still return the precise technical message, while the caller translates it for the user.

The translation can be stored in a database and cached in Redis or locally, then looked up by application_id + code before the response is sent.

5. Unified Handling of Return Information

With a unified code scheme, Nginx or APM tools can count the frequency and distribution of each API return code. Monitoring the occurrence of a specific code (e.g., 99999) enables automated anomaly alerts, and visualizing code statistics with pie charts helps identify systemic or business‑process issues.

In summary, a well‑designed error‑code system improves communication efficiency and lowers maintenance effort.