Design Principles and Standards for Error Codes in Service Development

Different development teams have their own habits for error‑code design. This article, based on insights from Alibaba Entertainment technology expert Chang Tong, discusses how to create reasonable error‑code specifications for both log‑oriented and external‑facing scenarios.

Output paths of error codes

Log‑oriented: transmitted within a service and ultimately written to logs; also used for inter‑service communication within a domain.

External transmission: passed from one domain to another, from backend to frontend, via OpenAPI, or between different domains.

Error‑code usage scenarios

Configure monitoring dashboards.

Quickly locate problems through log analysis.

Pass error codes between backend services.

Display user‑friendly error prompts on the frontend or through OpenAPI.

The article aims to derive a reasonable error‑code convention from these scenarios, producing a standard for log‑oriented error codes and another for external transmission.

Principles of error‑code design (from the Alibaba Java Development Manual): quick source tracing, simple and memorable, standardized communication. Explanation: Over‑perfecting error codes makes them like obscure dictionary entries—precise but hard to carry and understand.

What is an error code?

A good error code should answer two fundamental questions: whose fault is it and where did it occur. However, merely indicating the source and location is not sufficient.

It must enable rapid identification of the error source.

It should be easy to remember and compare (e.g., suitable for direct equals checks).

It must allow lightweight offline communication without relying on documentation.

Design of log‑oriented error codes

Log‑oriented error codes serve two purposes: fast source tracing and building monitoring dashboards. The manual suggests a 13‑character string (10 meaningful characters plus three separators) composed of:

Application identifier (3 digits).

Functional domain identifier (3 digits).

Error type (1 letter).

Error code (3 digits).

Examples and visual diagrams illustrate this structure.

Design of external‑facing error codes

External error codes should be simple, memorable, and limited in quantity. The recommended format is a 5‑character string: a single letter indicating the error source (A = user, B = system, C = third‑party) followed by a four‑digit numeric identifier.

This format facilitates easy communication with external systems, front‑end error prompts, and API consumers.

Other recommendations

Avoid using enums for error codes to support internationalization (i18n).

When a placeholder is needed, return "00000".

References include the Alibaba Java Development Manual, Google API Design Guide, Alibaba Cloud error‑code documentation, and error‑code specifications from major platforms such as Google, Tencent, and Weibo.