Skip to content
ShopNexus Docs
On this page Status codes 1/2

Every error answer has the same body:

{
  "error": {
    "code": "invalid_request",
    "message": "request does not match the API description",
    "fields": { "phone_token": "required" },
    "trace_id": "4bf92f3577b34da6..."
  }
}
  • code is stable and snake_case. The app maps it to its own Vietnamese text.
  • message is English, for developers. Never show it to users.
  • fields appears on validation errors, one entry per invalid field, keyed by its JSON path. The value is the rule it broke, such as required, minLength or additionalProperties.
  • details carries values the client acts on, such as retry_after in seconds.
  • trace_id equals the Trace-Id response header. Quote it when reporting a problem; it finds the request in the logs and traces.

Status codes

StatusMeaningTypical codes
400The request does not match the specinvalid_request, malformed_json
401No valid credentialsunauthenticated, invalid_token, invalid_refresh_token, session_revoked, session_expired, invalid_phone_token
403The account is suspendedaccount_suspended
404No such resource for this callerlisting_not_found, deal_not_found, …
409The write collided with anothertry_again
413The body is over 1 MBbody_too_large
422Well formed, but a rule refuses itone code per rule, such as invalid_phone
428The caller must do something firstreauth_required
429Rate limitedsee details.retry_after
500Unexpected failureinternal
503A service the request needs is downunavailable

A resource the caller may not see answers 404, the same as one that does not exist. Another account’s session, for example, is 404.

try_again is shared by every module: the write lost a race with another write to the same record, and sending it again is safe. Each operation in the spec lists the codes it can return, so check the operation before handling a code.

The real cause of a 500 goes to the server log only and never into the body.

Codes by use case

Each exception flow of a use case that ends on an error code lists it in the registry. The table below is built from that list; a code missing here is either shared by every module or not yet traced to a use case.

ShopNexus Docs
EN VI

Suggested for this page

Quick actions