trpc.group/trpc-go/trpc-go@v1.0.3/errs/README.md (about) 1 English | [中文](README.zh_CN.md) 2 3 # tRPC-Go Error Code Definition 4 5 6 ## Introduction 7 8 All languages of tRPC frameworks use a unified error definition consisting of an error code `code` and an error description `msg`. This differs from the Golang standard library's error, which contains only a string. Therefore, in tRPC-Go, the `errs` package is used to encapsulate error types, making it easier for users to work with errors. When a user needs to return an error, use `errs.New(code, msg)` to create the error instead of using the standard library's `errors.New(msg)` as shown below: 9 10 ```golang 11 func (s *greeterServerImpl) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) { 12 if failed { // Business logic failure 13 // Define an error code and return the error message to the caller 14 return nil, errs.New(int(your-err-code), "your business error message") 15 } 16 return &pb.HelloRepley{}, nil // Business logic succeeded 17 } 18 ``` 19 20 ## Error Code Type 21 22 tRPC-Go error codes are divided into `framework` errors, `callee framework` errors, and `business` errors. 23 24 ### Framework Errors 25 26 These are automatically returned by the current service's framework, such as timeouts, decoding errors, etc. All framework error codes used by tRPC are defined in [trpc.proto](https://github.com/trpc-group/trpc/blob/main/trpc/trpc.proto). 27 28 - 0-100: Server errors, indicating errors that occur before entering the business logic, such as when the framework encounters an error before processing the request from the network layer. It doesn't affect the business logic. 29 - 101-200: Client errors, which means errors that occur at the client level when invoking downstream services. 30 - 201-400: Streaming errors. 31 32 Typical log representation: 33 34 ```golang 35 type:framework, code:101, msg:xxx timeout 36 ``` 37 38 ### Callee Framework Errors 39 40 These are the error codes returned by the framework of the callee service. They may be transparent to the business development of the callee service, but they are clear indicators of errors returned by the callee service, and they have no direct relation to the current service. Typically, these errors are caused by parameter issues in the current service, and solving them requires checking request parameters and collaborating with the callee service. 41 42 Typical log representation: 43 44 ```golang 45 type:callee framework, code:12, msg:rpcname:xxx invalid 46 ``` 47 48 ### Business Errors 49 50 These are the error codes returned by the business logic of the callee service. Note that these error types are specific to the business logic of the callee service and are defined by the callee service itself. The specific meaning of these codes should be checked in the documentation of the callee service or by consulting the callee service's developers. 51 52 tRPC-Go recommends using `errs.New` to return business error codes when there is a business error, rather than defining error codes in response messages. Error codes and response messages are mutually exclusive, so if an error is returned, the framework will ignore the response message. 53 54 It is recommended that user-defined error codes start from 10000. 55 56 Typical log representation: 57 58 ```golang 59 type:business, code:10000, msg:xxx fail 60 ``` 61 62 ## Error Code Meanings 63 64 **Note: The following error codes refer to framework errors and callee framework errors. Business error codes are defined by the callee service and should be checked in the callee service's documentation or by consulting the callee service's developers. Error codes provide a general categorization of error types; specific error causes should be examined in the error message.** 65 66 | Error Code | Meanings | 67 | :--------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 68 | 0 | Success | 69 | 1 | Server decoding error, usually caused by misalignment or lack of synchronization of pb fields between caller and callee services, leading to failed unpacking. To resolve, ensure that both services are updated to the latest version of pb and keep pb synchronized. | 70 | 2 | Server encoding error, serialization of response packets failed, typically due to issues with pb fields, such as setting binary data with invisible characters to a string field. Check the error message for details. | 71 | 11 | Server doesn't have the corresponding service implementation. | 72 | 12 | Server doesn't have the corresponding interface implementation, calling function was incorrect. | 73 | 21 | Server-side business logic processing time exceeded the timeout, exceeding the link timeout or message timeout. | 74 | 22 | Server is overloaded, typically because the callee server used a overload control plugin. | 75 | 23 | The request is rate-limited by the server. | 76 | 24 | Server full-link timeout, i.e., the timeout given by the caller was too short, and it did not even enter the business logic of this service. | 77 | 31 | Server system error, typically caused by panic, most likely a null pointer or array out of bounds error in the called service. | 78 | 41 | Authentication failed. | 79 | 51 | Request parameters validates failed. | 80 | 101 | Timeout when making a client call. | 81 | 102 | Full-link timeout on the client side, meaning the timeout given for this RPC call was too short, potentially because previous RPC calls had already consumed most of the time. | 82 | 111 | Client connection error, typically because the callee service is not listening on the specified IP:Port or the callee service failed to start. | 83 | 121 | Client encoding error, serialization of request packets failed. | 84 | 122 | Client decoding error, typically due to misalignment of pb. | 85 | 123 | Rate limit exceeded by the client. | 86 | 124 | Client overload error. | 87 | 131 | Client IP routing error, typically due to a misspelled service name or no available instances under that service name. | 88 | 141 | Client network error. | 89 | 151 | Response parameters validates failed. | 90 | 161 | Request canceled prematurely by the caller caller. | 91 | 171 | Client failed to read frame data. | 92 | 201 | Server-side streaming network error. | 93 | 351 | Client streaming data reading failed. | 94 | 999 | Unknown error, typically occurs when the callee service uses `errors.New(msg)` from the Golang standard library to return an error without a numeric code. | 95 96 ## Implementation 97 98 The specific implementation structure of error is as follows: 99 100 ```golang 101 type Error struct { 102 Type int // Error code type: 1 for framework errors, 2 for business errors, 3 for callee framework errors 103 Code int32 // Error code 104 Msg string // Error message 105 Desc string // Additional error description, mainly used for monitoring prefixes, such as "trpc" for tRPC framework errors and "http" for HTTP protocol errors. Users can capture this error by implementing filters and change this field to report monitoring data with any desired prefix. 106 } 107 ``` 108 109 Error handling process: 110 111 - When the server returns a business error using `errs.New`, the framework fills this error into the `func_ret` field in the tRPC protocol header. 112 - When the server returns a framework error using `errs.NewFrameError`, the framework fills this error into the `ret` field in the tRPC protocol header. 113 - When the server framework responds, it checks whether there is an error. If there is an error, the response data is discarded. Therefore, when an error is returned, do not attempt to return data in the response. 114 - When the client invokes an RPC call, the framework needs to encode the request before sending the request downstream. If an error occurs before sending the network data, it directly returns `Framework` error to the user. If the request is successfully sent and a response is received, but a framework error is detected in the response's protocol header, it returns `Callee Framework` error. If a business error is detected during parsing, it returns `Business` error.