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

# Response Format

> Understand the standardized response structure

## Standardized Structure

All OneClickDz Flexy API v3 endpoints follow a consistent response structure, making it easy to handle responses across your application.

## Success Response

When a request is successful, the response follows this structure:

```json theme={null}
{
  "success": true,
  "data": {
    // endpoint-specific data
  },
  "meta": {
    "timestamp": "2025-10-29T00:00:00.000Z"
    // additional metadata (pagination, etc.)
  },
  "requestId": "req_1234567890_abc123"
}
```

### Fields

<ResponseField name="success" type="boolean" required>
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="object" required>
  Contains the response payload. Structure varies by endpoint.
</ResponseField>

<ResponseField name="meta" type="object">
  Additional metadata about the response

  <Expandable title="properties">
    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of when the response was generated
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination details (for list endpoints)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string">
  Unique identifier for this request. Use this when contacting support.
</ResponseField>

## Error Response

When a request fails, the response follows this structure:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // additional error context
    }
  },
  "requestId": "req_1234567890_abc123"
}
```

### Fields

<ResponseField name="success" type="boolean" required>
  Always `false` for error responses
</ResponseField>

<ResponseField name="error" type="object" required>
  Contains error information

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Machine-readable error code (e.g., `NO_BALANCE`, `INVALID_PHONE`)
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error description
    </ResponseField>

    <ResponseField name="details" type="object">
      Additional context about the error (optional)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string">
  Unique identifier for this request. Include this when reporting issues.
</ResponseField>

## Response Examples

### Account Balance

```json theme={null}
{
  "success": true,
  "data": {
    "balance": 1326.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}
```

### Mobile Top-Up Send

```json theme={null}
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "my-order-123",
    "newBalance": 826.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:59.454Z"
  }
}
```

### List Transactions (with Pagination)

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "type": "FLEXY",
        "amount": 500,
        "time": "2025-10-29T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.852Z"
  }
}
```

## Pagination

List endpoints include pagination in the response:

```json theme={null}
{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  }
}
```

### Pagination Fields

<ResponseField name="page" type="integer">
  Current page number (1-indexed)
</ResponseField>

<ResponseField name="pageSize" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of pages available
</ResponseField>

<ResponseField name="totalResults" type="integer">
  Total number of items across all pages
</ResponseField>

### Pagination Query Parameters

Control pagination using these query parameters:

| Parameter  | Type    | Default | Description                       |
| ---------- | ------- | ------- | --------------------------------- |
| `page`     | integer | 1       | Page number (minimum: 1)          |
| `pageSize` | integer | 20      | Items per page (min: 1, max: 100) |

<Tip>Always check `totalPages` to know when to stop paginating.</Tip>

## HTTP Status Codes

The API uses conventional HTTP status codes:

| Status Code | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `200`       | Success - Request completed successfully                |
| `400`       | Bad Request - Invalid parameters or validation error    |
| `401`       | Unauthorized - Invalid or missing API key               |
| `403`       | Forbidden - Insufficient balance or permissions         |
| `404`       | Not Found - Resource doesn't exist                      |
| `429`       | Too Many Requests - Rate limit exceeded                 |
| `500`       | Internal Server Error - Something went wrong on our end |
| `503`       | Service Unavailable - Temporary service disruption      |

<Note>
  Even for non-200 status codes, the response follows the standard error format.
</Note>

## Request ID

Every response includes a unique `requestId`:

```json theme={null}
{
  "success": true,
  "data": {...},
  "requestId": "req_1761698159_abc123xyz"
}
```

### Uses for Request ID

<CardGroup cols={2}>
  <Card title="Debugging" icon="bug">
    Track requests through logs and identify issues
  </Card>

  {" "}

  <Card title="Support" icon="life-ring">
    Include in support tickets for faster resolution
  </Card>

  {" "}

  <Card title="Auditing" icon="clipboard-check">
    Correlate requests with transactions
  </Card>

  <Card title="Monitoring" icon="chart-line">
    Track request flow across systems
  </Card>
</CardGroup>

<Tip>
  Always log the `requestId` for every API call you make. It's invaluable for
  debugging.
</Tip>

## Content Type

All requests and responses use JSON:

### Request Headers

```http theme={null}
Content-Type: application/json
X-Access-Token: YOUR_API_KEY
```

### Response Headers

```http theme={null}
Content-Type: application/json; charset=utf-8
X-Request-ID: req_1761698159_abc123xyz
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1761698219
```

## Handling Responses

### Best Practices

<AccordionGroup>
  <Accordion title="Always Check success Field" icon="check-circle">
    ```javascript theme={null}
    const response = await fetch(url, options);
    const data = await response.json();

    if (data.success) {
      // Handle success
      console.log(data.data);
    } else {
      // Handle error
      console.error(data.error.code, data.error.message);
    }
    ```
  </Accordion>

  <Accordion title="Log Request IDs" icon="file-lines">
    ```javascript theme={null}
    console.log(`Request ${data.requestId}: ${data.success ? 'Success' : 'Failed'}`);

    if (!data.success) {
      console.error(`Error ${data.error.code}: ${data.error.message}`);
    }
    ```
  </Accordion>

  <Accordion title="Handle Pagination" icon="list">
    ```javascript theme={null}
    let page = 1;
    let allItems = [];

    while (true) {
      const response = await fetch(`${url}?page=${page}&pageSize=100`);
      const data = await response.json();
      
      if (!data.success) break;
      
      allItems.push(...data.data.items);
      
      if (page >= data.data.pagination.totalPages) break;
      page++;
    }
    ```
  </Accordion>

  <Accordion title="Parse Timestamps" icon="clock">
    ```javascript theme={null}
    const timestamp = new Date(data.meta.timestamp);
    console.log(`Response generated at: ${timestamp.toLocaleString()}`);
    ```
  </Accordion>
</AccordionGroup>

## TypeScript Types

If you're using TypeScript, here are helpful type definitions:

```typescript theme={null}
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    timestamp: string;
    pagination?: {
      page: number;
      pageSize: number;
      totalPages: number;
      totalResults: number;
    };
  };
  requestId?: string;
}

interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
  };
  requestId?: string;
}

type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;

// Usage
async function getBalance(): Promise<number> {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/account/balance",
    {
      headers: { "X-Access-Token": API_KEY },
    }
  );

  const data: ApiResponse<{ balance: number }> = await response.json();

  if (data.success) {
    return data.data.balance;
  } else {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/en/api-reference/error-handling">
    Learn how to handle errors effectively
  </Card>

  <Card title="Core Endpoints" icon="code" href="/en/api-reference/core/health-check">
    Explore all available endpoints
  </Card>
</CardGroup>