Response Format & Errors

The standard success envelope, pagination shape, and error format used everywhere

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