> ## Documentation Index
> Fetch the complete documentation index at: https://secdocs.asikoexpress.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "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`.                                                                                                     |

<Note>
  A single-entity response (e.g. fetching one order) puts that entity directly in `data` — there's
  no extra nesting.
</Note>

## Pagination

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

```json theme={null}
{
  "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):

```json theme={null}
{
  "success": false,
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "path": "phone", "message": "Required" }
  ]
}
```

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

```json theme={null}
{
  "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](/rate-limiting) |
| `500`  | Unexpected server error                                   |