Error codes and i18n
The unified response envelope, error-code ranges, and text in three languages.
Response shape
{
"code": 0,
"message": "ok",
"traceId": "6b2f0c8e1a...",
"data": { }
}
- The HTTP status is always 200; the business result is in
code. - Null fields are omitted from the JSON, and the front-end contract relies on that.
- The response body comes from the shared utility only;
new ResponseResult<>()is forbidden.
Ranges
| Range | Meaning |
|---|---|
0 | success |
400001 | parameter and validation problems (including illegal sort fields) |
401001 | not signed in |
403001 | no permission |
500003 | system busy (fallback) |
Tip: the error-code implementation in code is authoritative. A new error code must add text in all three languages; missing one fails the build.
Adding an error code
- Implement the error-code interface with the range and default text.
- Add one entry to each of the three i18n text files.
- Throw the business exception in code; the global handler translates it into the response.
Debugging
When a user reports an error, the traceId in the response is enough to reconstruct the whole request in the logs.
Last updated 2026-10-09Edit this page →