Designing Effective Error Codes: Principles, Standards, and Best Practices

Introduction

Different development teams adopt various styles for error codes. This article shares the views of an Alibaba entertainment technology expert on error‑code design, aiming to derive a reasonable error‑code specification for both log‑oriented and external‑facing scenarios.

Output Paths for Error Codes

Log‑Oriented

Service‑internal transmission ultimately output to logs.

Domain‑internal services (e.g., between e‑commerce systems) also target logs.

External‑Facing

Domain‑to‑outside transmission.

Server to frontend.

OpenAPI error codes.

Inter‑domain communication within the same organization.

Error‑Code Usage Scenarios

Configure monitoring dashboards via error codes.

Rapid problem diagnosis through logs.

Backend service error propagation.

Frontend error prompts / OpenAPI responses.

The goal is to discuss these scenarios and propose two standards: one for logs and one for external transmission.

What Is an Error Code?

An error code should answer: whose fault is it and where did it occur? A good error code must enable quick source identification, be easy to remember and compare, and allow lightweight offline communication without relying on documentation.

Principles for error‑code design: fast traceability, simple memorability, standardized communication. Explanation: Over‑engineered codes become like obscure dictionary entries—precise but hard to carry and understand. Positive example: an error code should reveal who is at fault and where the problem lies.

Why These Principles Matter

They apply equally to user‑facing error codes. Without a unified standard, teams waste time locating the source of an error, leading to costly communication overhead.

Log‑Oriented Error Code Specification

According to the Alibaba Java Development Manual, a log‑oriented error code is a 13‑character string (10 meaningful characters plus 3 separators) composed of:

Application identifier (3 digits).

Functional domain identifier (3 digits).

Error type (1 letter).

Error number (3 digits).

Example diagram:

External‑Facing Error Code Specification

For external transmission, a 5‑character code is recommended:

Type letter indicating source (A: user, B: system, C: third‑party).

Four‑digit numeric identifier (0001‑9999).

Benefits: easy to remember and suitable for cross‑system communication.

Comparison with Other Companies

Google API : Fully numeric codes tightly coupled with HTTP status codes, lacking clear categorization and self‑explanatory power.

Tencent OpenAPI (WenZhi) : Also fully numeric, without obvious classification fields, making memorization difficult.

Weibo API : Another fully numeric scheme with similar drawbacks.

Additional Recommendations

When a code must be filled but no meaningful value exists, use five zeros: 00000.

References

Alibaba Java Development Manual

Google API Design Guide

Alibaba Cloud File Storage Error Codes

Weibo Open Platform API Error Codes

Tencent Open Platform Error Codes