• notice
  • Congratulations on the launch of the Sought Tech site

How to design API return code (error code)?

I. Introduction

When the client requests the API, it usually needs to use the return code to judge whether the result returned by the API meets expectations, and how to deal with the returned content, etc.

I believe that many students have suffered from the confusion of return code definitions. Some APIs use return codes of int type, some of which are string types, some use 0 to indicate success, some use 1 to indicate success, and some use "true" to indicate success. When something like this happens, all I can say is: headache

The design of the API return code should be taken seriously, after all, a good return code design can reduce communication costs and program maintenance costs

2. HTTP status code reference

Taking the HTTP status code as an example, in order to express and distinguish the meaning of the status code more clearly, the HTTP status is segmented.

sectionsegment description
1XXInformation, the server receives the request and needs the requester to continue to perform the operation
2XXSuccess, the operation was successfully received and processed
3XXRedirected, further action is required to complete the request
4XXClient error, the request contained syntax errors or could not be completed
5XXServer error, the server encountered an error while processing the request

For back-end development, what we usually see are:

2XX status code, such as 200->request succeeded,

5XX status code, such as 502->server exception, usually means that the service is not running normally, or the code execution error

The cause of the problem can be preliminarily judged by the status code, and the design idea of the HTTP status is worth learning.

3. Parameter convention

Although it is a return code design, only the code is not enough, and there must be a corresponding message so that people can understand it

codeintreturn code
messagestringReturn Code Description

Referring to the idea of HTTP status code, we segment the error code

return code valueillustrate
99999An unknown exception occurred in the system
10000-19999Parameter validation error
20000-29999A step execution failed
30000-39999Step B failed to execute

Through this design, both programs and people can easily distinguish the returned results of the API, the key is unity!

4. Personalized Message

Usually our messages are written for engineers to read, but in different scenarios, the same error may require users to see different error prompts.

For example, 20000-29999 indicates that the order creation failed:

  • 20001, order creation failed, there are orders in progress

  • 20002, order creation failed, the last order is being queued for creation

If these two error situations are for users, they may only be suitable for viewing: Sorry, you have an order in progress, please go to my order list to process it.

But for the API, the information returned must be accurate, but what the user sees must be translated. This translation can be done by the caller, but usually it is better for the API provider to provide personalized Message capabilities.

We can configure the translated message to the database and cache it to Redis or API native

10000120001Sorry, you have an order in progress, please go to my order list to process it.
10000120002Sorry, you have an order in progress, please go to my order list to process it.

Then when the request processing is finished and is about to return, match and replace the message according to the application_id+code


In this way, we can allow users of mobile APPs, users of WeChat applets, and corporate users who place orders on the web to see different messages.

5. Unified processing of returned information

With a unified code, we can use Nginx or APM tools to count the number and distribution of API request codes.

We can make API exception alarms based on the number of 99999 per unit time

We can help us find problems in the system and business process according to the pie chart returned by Code


In short, a good return code design can help us improve communication efficiency and reduce code maintenance costs


Technical otaku

Sought technology together

Related Topic


Leave a Reply