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:
{
"success": true,
"data": {
// endpoint-specific data
},
"meta": {
"timestamp": "2025-10-29T00:00:00.000Z"
// additional metadata (pagination, etc.)
},
"requestId": "req_1234567890_abc123"
}
Fields
Always true for successful responses
Contains the response payload. Structure varies by endpoint.
Additional metadata about the response
ISO 8601 timestamp of when the response was generated
Pagination details (for list endpoints)
Unique identifier for this request. Use this when contacting support.
Error Response
When a request fails, the response follows this structure:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
// additional error context
}
},
"requestId": "req_1234567890_abc123"
}
Fields
Always false for error responses
Contains error information
Machine-readable error code (e.g., NO_BALANCE, INVALID_PHONE)
Human-readable error description
Additional context about the error (optional)
Unique identifier for this request. Include this when reporting issues.
Response Examples
Account Balance
{
"success": true,
"data": {
"balance": 1326.13
},
"meta": {
"timestamp": "2025-10-29T00:35:58.710Z"
}
}
Mobile Top-Up Send
{
"success": true,
"data": {
"topupId": "6901616fe9e88196b4eb64b0",
"topupRef": "my-order-123",
"newBalance": 826.13
},
"meta": {
"timestamp": "2025-10-29T00:35:59.454Z"
}
}
{
"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"
}
}
{
"success": true,
"data": {
"items": [...],
"pagination": {
"page": 1,
"pageSize": 20,
"totalPages": 10,
"totalResults": 195
}
}
}
Current page number (1-indexed)
Total number of pages available
Total number of items across all pages
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number (minimum: 1) |
pageSize | integer | 20 | Items per page (min: 1, max: 100) |
Always check totalPages to know when to stop paginating.
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 |
Even for non-200 status codes, the response follows the standard error format.
Request ID
Every response includes a unique requestId:
{
"success": true,
"data": {...},
"requestId": "req_1761698159_abc123xyz"
}
Uses for Request ID
Debugging
Track requests through logs and identify issues
Support
Include in support tickets for faster resolution
Auditing
Correlate requests with transactions
Monitoring
Track request flow across systems
Always log the requestId for every API call you make. It’s invaluable for
debugging.
Content Type
All requests and responses use JSON:
Content-Type: application/json
X-Access-Token: YOUR_API_KEY
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
Always Check success Field
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);
}
console.log(`Request ${data.requestId}: ${data.success ? 'Success' : 'Failed'}`);
if (!data.success) {
console.error(`Error ${data.error.code}: ${data.error.message}`);
}
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++;
}
const timestamp = new Date(data.meta.timestamp);
console.log(`Response generated at: ${timestamp.toLocaleString()}`);
TypeScript Types
If you’re using TypeScript, here are helpful type definitions:
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
