Response Format & Errors

Every success response — from every service, through the gateway — is wrapped in the same envelope. You can rely on this shape for any 2xx response in this reference, even where an individual endpoint’s schema below doesn’t spell it out explicitly.

Success envelope

{
  "message": "Success",
  "status": 200,
  "data": { },
  "meta": null
}

Field	Description
`message`	Human-readable summary. Defaults to `"Success"`; some endpoints set a more specific one (e.g. `"Registration successful. Check your email for a verification code."`).
`status`	The same value as the HTTP status code.
`data`	The actual payload. `null` for endpoints with nothing meaningful to return (e.g. `204`-style actions that still respond with a body).
`meta`	Present on paginated list endpoints (see below); otherwise `null`.

A single-entity response (e.g. fetching one order) puts that entity directly in data — there’s no extra nesting.

Pagination

List endpoints that paginate (orders, points history, product listings, etc.) populate meta:

{
  "message": "Success",
  "status": 200,
  "data": [ ],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Pass page and limit as query parameters; both are optional and endpoint-specific defaults apply (commonly page=1&limit=20).

Errors

Errors are not wrapped in the envelope above — they use a flatter shape so success: false is always the first thing to check. Validation errors (400, request body failed schema validation):

{
  "success": false,
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "path": "phone", "message": "Required" }
  ]
}

All other errors (auth failures, not-found, conflicts, server errors):

{
  "success": false,
  "statusCode": 404,
  "message": "Order not found"
}

message can also be an array of strings for some framework-level validation failures. 500 responses always return the generic message "Internal server error" — details are logged server-side, never sent to the client.

Status	Meaning
`400`	Malformed request or failed validation
`401`	Missing, invalid, or expired bearer token
`403`	Authenticated, but missing the required role
`404`	Resource doesn’t exist, or doesn’t belong to the caller
`409`	Conflict (e.g. duplicate email on registration)
`429`	Rate limit exceeded — see Rate Limiting
`500`	Unexpected server error

Getting Started

Real-time

Appendix

Response Format & Errors

Success envelope

Errors

​Success envelope

​Pagination

​Errors

Success envelope

Pagination

Errors