Designing Effective API Error Codes and Their Propagation in Complex Systems

API and database design are crucial for software architecture, affecting stability, scalability, and maintainability.

Importance of API Design

APIs provide abstraction, hide implementation details, and ensure backward compatibility, allowing internal changes without affecting callers.

Importance of Database Design

Good database design supports extensibility, maintainability, and simplifies data migration through proper indexing, sharding, and version control.

API Error Code Fundamentals

Error codes abstract errors, helping users and developers identify the nature of failures. Effective error messages should be clear, concise, and actionable.

Error Code Design Principles

Fast traceability: codes should indicate the system and module where the problem occurs.

Simplicity and memorability: a clear structure aids comparison and handling.

Descriptive messages: messages must be understandable to both developers and end‑users.

Response Structure

A typical API response contains code , message , and data fields.

public class PromiseResponse
{
    // 错误编码
    private String code;
    // 提示信息
    private String message;
    // 业务数据
    private T data;
}

{
  "code": 200,
  "message": "成功",
  "data": { ... }
}

Error Propagation

When an API depends on downstream services, error codes should be translated or enriched rather than blindly propagated, hiding internal details while providing useful information.

Bad Practices

Examples of poor error code design include lack of rules, overly granular codes, and unclear messages.

Industry Cases

References to JD Cloud and Google API error code specifications illustrate differing approaches.

Full‑Link Error Code System

Proposes a trace‑id based logging scheme where each log entry records traceId|appErrorCode|description , enabling end‑to‑end error tracing across services.

1677474.49460.17235995037011944.3460091.193151.9140|WMS_10001|调用Promise（系统B）系统异常，缺少预计妊投时间

Collecting these logs into a message queue allows analysis, storage in MySQL/Elasticsearch, and real‑time alerts.

Overall, well‑designed API error codes improve system maintainability, debugging efficiency, and user experience.