How Detailed Should API Return Codes Be to Avoid Back-and-Forth During Integration?

How detailed should API return codes be? Based on 2026 delivery practices, the passing line is: after receiving the return code, the caller can decide the next step directly without further clarification. The typical range is to keep business return codes within 20–50, covering three basic outcomes: success, retryable failure, and non-retryable failure—rather than creating a new code for every exception.

Return Code Granularity: How Fine Is Qualified?

Codes that are too coarse only tell the caller "it failed," forcing them to check logs or ask the backend; codes that are too fine split "incorrect parameter format" and "parameter out of range" into separate codes while the caller's handling is exactly the same, adding needless comprehension cost. A common practice in 2026 is to use a main code for the error category and sub-codes or error messages for details, rather than stuffing everything into the return code.

A reusable criterion: if two error scenarios require exactly the same handling branch in the caller's code, they do not need two distinct return codes; if the handling differs, even if they look like similar errors, they should be separated.

• Keep a single success code; do not use multiple numbers for the same success state.
• Failure codes must at least distinguish "retryable" from "non-retryable"—the most critical decision variable for callers.
• Keep error message fields separate; do not let the return code carry descriptive text itself.

Four-Dimensional Review Framework for Return Code Design

Why four dimensions? Once a return code is written into the caller's code, changes can multiply the cost. Reviewing against the four dimensions—caller action, retry policy, manual intervention, and compatibility evolution—can eliminate most integration friction before release.

1. Check by caller action: For each return code, write down the action the caller will take; if you cannot, the code is redundant or unclear.
2. Check by retry policy: Specify which codes allow retries and which do not, and give recommended wait times—for example, the typical range is retry after 2–5 seconds—to prevent blind loops.
3. Check by manual intervention: Mark codes that require manual handling by ops or developers, such as database connection exhaustion or configuration errors; do not just return a generic "system error."
4. Check by compatibility evolution: The meaning of return codes must not be arbitrarily changed after release; adding new codes should be easy, changing semantics should be hard, and every change should be recorded in the API documentation's change log.

In real projects in 2026, this framework is typically applied during the API design review stage. What counts as passing? Every item should have a concrete example, rather than saying "handle it as usual."

Common Pitfalls: How Return Codes Turn from Convenience to Trouble

There are three common pitfalls. First, using meaningless numeric strings as return codes, such as 10086 or 20001, forcing callers to look them up in a table. Second, mixing return codes with HTTP status codes—for example, using 404 to indicate business data does not exist—which causes front-end interceptors and business code to conflict. Third, for "simplicity," returning 1 for every failure, so when callers log errors, backend troubleshooting relies on guesswork.

During project delivery at Xiyue Company, a client once required return codes to be defined per exception. Before integration, over 300 codes were counted, more than half of which led to identical handling actions; maintaining the lookup table alone took two weeks. After switching to a "main code + error detail" structure, the code table dropped to around 40, and integration time actually shortened by one-third. The delay caused by this change highlights that modifying return codes before release requires synchronized front-end and back-end adjustments, with costs higher than expected. During delivery, first verify the external release timeline of return codes; once integration begins, any further changes must go through change review.

Another hidden pitfall is duplicate return code values. For example, 0 might mean success in module A but an unknown exception in module B; a global check in the caller would then be wrong. A common practice is to use a module prefix plus a sequence number, such as 1001 for order-module errors and 2001 for user-module errors, and to run a duplicate-check script before release.

• Do not use negative integers or extremely large integers as return codes; they can cause type-conversion issues.
• The return code documentation should specify "conditions for adding" and "requirements for changing"—for example, before adding a code, confirm whether one with the same handling action already exists.
• The error detail field may carry context from the backend, but must not contain sensitive information such as SQL statements or full stack traces.

Return Codes vs. HTTP Status Codes: Who Handles What

HTTP status codes answer "whether the request was correctly received and processed by the server," while business return codes answer "whether the business result meets expectations." Mapping all business failures to HTTP 4xx/5xx can mislead log monitoring and gateway policies; conversely, returning HTTP 200 for everything prevents callers from using existing tools to quickly detect service anomalies.

A common approach in 2026 is: internal APIs prefer HTTP 200 + business return codes, letting business errors travel in a unified response body; externally exposed RESTful APIs use HTTP status codes for coarse-grained status, with fine-grained errors in the code field of the response body. Both approaches have applicable scenarios, depending on the team's trade-off between caller cost and clarity.

• Option A: HTTP 200 + business code. Pros: simple logic for gateways, monitoring, and front-end interceptors; Cons: when the service is actually down, callers need extra handling for HTTP-level exceptions.
• Option B: HTTP 4xx/5xx + business code. Pros: conforms to HTTP semantics, making logs and monitoring more intuitive; Cons: front-end and back-end must agree on "which status codes can be ignored and which must be intercepted."

If the team lacks a dedicated gateway or unified framework, Option A is recommended first, separating business errors from transport errors. What counts as passing? The caller can make a decision by looking at the response body alone, without checking whether the combination of HTTP status code and business code is contradictory.

Applicable Scenarios and Boundaries

This return-code design approach suits scenarios with clear callers and predictable flows, such as admin systems, internal service APIs, and mobile backend interfaces. In projects, a typical cycle is to spend half a day to one day during API design to finalize the code table, make on-demand adjustments during integration, and keep it stable after release. For static resource services accessed directly by browsers, file upload/download, or streaming interfaces, return codes do not need business-level granularity—HTTP status codes plus simple error messages are sufficient.

Complex return codes are unnecessary in the following cases: the API is used only by one or two front-end pages from your own team, and the team can make synchronized changes at any time; the project is a short-term demo prototype; or the underlying services are entirely managed by infrastructure with no custom business logic. The boundary: return codes are a "contract," and only deserve design cost when multi-party collaboration and long-term maintenance are required.

FAQ

How many return codes are appropriate?

Based on typical project experience, 20–50 business return codes are enough for most admin interfaces. Fewer than 10 may be too coarse; more than 100 often means overlap. The key is whether the caller's handling actions are identical.

Can return codes and HTTP status codes be shared directly?

Direct sharing is not recommended. HTTP status codes handle transport and request semantics, while business return codes handle business outcomes. Mixing them can cause gateway monitoring and front-end interceptors to interfere with each other; it is best to design them separately.

What should I do if return codes are insufficient during API integration?

First check whether a code with the same handling action already exists—if so, reuse it. If not, add a sub-code or main code, but update the API documentation and inform callers synchronously; keep a record of the change.

Should return codes be written into the API documentation?

Yes, and each code should clearly state its trigger condition, the caller's suggested action, and whether it is retryable. A common pitfall is updating documentation after code; include the documentation in code review.

Action guide: First, use the four-dimensional framework above to review your current API return code table, annotating each code's caller action and retry policy. Then merge duplicate codes and have new codes go through review. Finally, run a script to validate return code uniqueness. This method suits common admin and API projects in 2026, not pure static resources or temporary scripts. Boundary: if you are the only caller, no return code design will cause integration issues.