Error Handling - OneClickDz Flexy API

Error Response Structure

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // additional context
    }
  },
  "requestId": "req_abc123"
}

HTTP Status Codes

Status	Category	Description
`400`	Client Error	Invalid request parameters or validation error
`401`	Authentication	Invalid or missing API key
`403`	Authorization	Insufficient permissions or balance
`404`	Not Found	Resource doesn’t exist
`429`	Rate Limit	Too many requests
`500`	Server Error	Internal server error
`503`	Unavailable	Service temporarily unavailable

Common Error Codes

Authentication Errors (401)

MISSING_ACCESS_TOKEN

Message: Access token is required
Cause: The X-Access-Token header is missing
Action: Include your API key in the header

// ✅ Correct
fetch(url, {
  headers: { 'X-Access-Token': 'YOUR_API_KEY' }
})

INVALID_ACCESS_TOKEN / ERR_AUTH

Message: The provided access token is invalid
Cause: API key is incorrect, expired, or revoked
Action:
- Verify API key is correct
- Generate a new key if needed
- Don’t log sensitive key values
- Contact support if issue persists

Authorization Errors (403)

NO_BALANCE / INSUFFICIENT_BALANCE

Message: Insufficient balance
Cause: Account balance is too low
Action:
- Check balance using /v3/account/balance before operations
- Display current balance to user
- Offer top-up option
- Don’t retry without adding funds

const balanceRes = await fetch('https://api.oneclickdz.com/v3/account/balance', {
  headers: { 'X-Access-Token': API_KEY }
});
const { data } = await balanceRes.json();

if (data.balance < requiredAmount) {
  throw new Error('Insufficient balance');
}

DUPLICATED_REF

Message: This reference ID is already in use
Cause: Reference already used in previous request
Action:
- Check status of existing order
- Generate new unique reference
- Don’t create duplicate orders

const ref = `order-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;

IP_BLOCKED

Message: Your IP has been temporarily blocked
Cause: Too many failed authentication attempts
Action:
- Wait 15 minutes for automatic unblock
- Verify correct API key
- Contact support if persists

IP_NOT_ALLOWED

Message: Your IP address is not whitelisted
Cause: IP whitelisting is enabled
Action: Add your IP to whitelist in dashboard

Validation Errors (400)

ERR_VALIDATION

Message: Validation error
Cause: Request parameters don’t meet requirements
Common Issues: Missing fields, invalid data types, pattern mismatch
Action:
- Validate input client-side first
- Check error.details for specific field issues
- Don’t retry without fixing the issue

// Validate before sending
function validateTopupRequest(data) {
  const errors = [];
  
  if (!data.plan_code) {
    errors.push({ field: 'plan_code', message: 'Plan code is required' });
  }
  
  if (!data.MSSIDN || !/^0[567][0-9]{8}$/.test(data.MSSIDN)) {
    errors.push({ field: 'MSSIDN', message: 'Invalid phone number format' });
  }
  
  if (isDynamicPlan(data.plan_code)) {
    if (!data.amount || data.amount < 50 || data.amount > 5000) {
      errors.push({ field: 'amount', message: 'Amount must be between 50 and 5000' });
    }
  }
  
  return errors.length > 0 ? { valid: false, errors } : { valid: true };
}

ERR_PHONE

Message: Invalid phone number
Cause: Phone number is incorrect or doesn’t exist
Action: Use /v3/internet/check-number to validate first

const checkRes = await fetch(
  `https://api.oneclickdz.com/v3/internet/check-number?type=ADSL&number=${number}`,
  { headers: { 'X-Access-Token': API_KEY } }
);

if (!checkRes.ok) {
  throw new Error('Invalid phone number');
}

ERR_STOCK

Message: Product out of stock
Cause: Requested product/card value is not available
Action:
- Check stock before ordering
- Offer alternative denominations
- Retry later

Not Found Errors (404)

NOT_FOUND - Message: Resource not found - Cause: The requested

resource doesn’t exist - Common Cases: Invalid order ID, invalid reference, deleted resource - Action: - Verify the ID/reference is correct

Check for typos - Handle gracefully in UI

Rate Limit Errors (429)

RATE_LIMIT_EXCEEDED

Message: Too many requests
Cause: Exceeded the rate limit
Limits: Sandbox: 60 req/min, Production: 120 req/min
Action: Implement exponential backoff with retry logic

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

Server Errors (500/503)

INTERNAL_SERVER_ERROR / INTERNAL_ERROR

Message: Developer was notified and will check shortly
Cause: Unexpected error on our servers
Action:
- Don’t refund immediately - wait 24 hours
- Save requestId for support
- Implement retry logic with backoff
- Contact support with details
- We’re automatically notified

if (response.status === 500) {
  console.error('Server error:', data.requestId);
  // Mark for review - don't refund yet
  await scheduleStatusCheck(orderId, 24 * 60 * 60 * 1000);
}

ERR_SERVICE

Message: Service temporarily unavailable
Cause: Service maintenance or temporary issue
Action:
- Show maintenance message
- Retry after delay
- Monitor for resolution

Implementation Best Practices

1. Always Check Success Field

const response = await fetch(url, options);
const data = await response.json();

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

2. Handle Specific Error Codes

async function sendTopUp(params) {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": API_KEY,
    },
    body: JSON.stringify(params),
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case "NO_BALANCE":
      case "INSUFFICIENT_BALANCE":
        throw new Error("Insufficient balance. Please add funds.");

      case "DUPLICATED_REF":
        return await checkOrderStatus(params.ref);

      case "ERR_VALIDATION":
        throw new Error(`Invalid input: ${data.error.message}`);

      case "INTERNAL_SERVER_ERROR":
      case "INTERNAL_ERROR":
        await scheduleStatusCheck(params.ref);
        throw new Error("Temporary error, checking status later");

      default:
        throw new Error(`${data.error.code}: ${data.error.message}`);
    }
  }

  return data.data;
}

3. Smart Retry Logic with Exponential Backoff

async function safeApiCall(apiFunction, options = {}) {
  const { maxRetries = 3, retryDelay = 1000, retryOn = [500, 503] } = options;

  let lastError;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiFunction();
    } catch (error) {
      lastError = error;

      // Don't retry on client errors (4xx)
      if (error.status >= 400 && error.status < 500) {
        throw error;
      }

      // Retry on specific status codes
      if (retryOn.includes(error.status) && attempt < maxRetries) {
        const delay = retryDelay * Math.pow(2, attempt - 1);
        console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms`);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }

  throw lastError;
}

// Usage
try {
  const result = await safeApiCall(() => sendMobileTopup(data), {
    maxRetries: 3,
    retryDelay: 2000,
  });
} catch (error) {
  handleError(error);
}

4. User-Friendly Error Messages

const errorMessages = {
  MISSING_ACCESS_TOKEN: "Authentication required. Please check your API key.",
  INVALID_ACCESS_TOKEN: "Invalid API key. Please verify your credentials.",
  ERR_AUTH: "Authentication failed. Please check your API key.",
  NO_BALANCE: "Insufficient balance. Please top up your account.",
  INSUFFICIENT_BALANCE: "Insufficient balance. Please top up your account.",
  DUPLICATED_REF: "This order was already processed.",
  ERR_VALIDATION: "Please check your input and try again.",
  ERR_PHONE: "Invalid phone number. Please verify and try again.",
  ERR_STOCK: "This product is currently out of stock.",
  NOT_FOUND: "The requested resource was not found.",
  RATE_LIMIT_EXCEEDED: "Too many requests. Please wait a moment and try again.",
  ERR_SERVICE: "Service temporarily unavailable. Please try again.",
  INTERNAL_SERVER_ERROR: "An error occurred. Our team has been notified.",
  INTERNAL_ERROR: "An error occurred. Our team has been notified.",
};

function getUserFriendlyMessage(errorCode, defaultMessage) {
  return (
    errorMessages[errorCode] ||
    defaultMessage ||
    "An unexpected error occurred."
  );
}

// Usage
if (!data.success) {
  const userMessage = getUserFriendlyMessage(
    data.error.code,
    data.error.message
  );
  showErrorToUser(userMessage);
}

5. Log Request IDs

function logError(error, context) {
  const errorLog = {
    timestamp: new Date().toISOString(),
    requestId: error.requestId,
    code: error.code,
    message: error.message,
    context: {
      userId: context.userId,
      operation: context.operation,
      // Don't log sensitive data
    },
  };

  // Log to your logging service
  logger.error("API Error", errorLog);

  // Alert on critical errors
  if (error.status >= 500) {
    alertOps("API Error", errorLog);
  }
}

Advanced Patterns

Circuit Breaker Pattern

Prevent cascading failures by stopping requests when error rate is high:

class CircuitBreaker {
  constructor(threshold = 5, timeout = 60000) {
    this.failureCount = 0;
    this.threshold = threshold;
    this.timeout = timeout;
    this.state = "CLOSED"; // CLOSED, OPEN, HALF_OPEN
    this.nextAttempt = Date.now();
  }

  async execute(fn) {
    if (this.state === "OPEN") {
      if (Date.now() < this.nextAttempt) {
        throw new Error("Circuit breaker is OPEN");
      }
      this.state = "HALF_OPEN";
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = "CLOSED";
  }

  onFailure() {
    this.failureCount++;
    if (this.failureCount >= this.threshold) {
      this.state = "OPEN";
      this.nextAttempt = Date.now() + this.timeout;
    }
  }
}

// Usage
const breaker = new CircuitBreaker(5, 60000);

try {
  const result = await breaker.execute(() => sendTopup(data));
} catch (error) {
  if (error.message === "Circuit breaker is OPEN") {
    showMaintenanceMessage();
  }
}

Error Monitoring

Track error patterns to identify issues early:

class ApiClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.errorStats = new Map();
  }

  trackError(errorCode) {
    const count = this.errorStats.get(errorCode) || 0;
    this.errorStats.set(errorCode, count + 1);
  }

  async request(url, options) {
    try {
      const response = await fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          "X-Access-Token": this.apiKey,
        },
      });

      const data = await response.json();

      if (!data.success) {
        this.trackError(data.error.code);

        // Alert if too many errors
        if (this.errorStats.get(data.error.code) > 10) {
          this.sendAlert(`High error rate: ${data.error.code}`);
        }
      }

      return data;
    } catch (error) {
      this.trackError("NETWORK_ERROR");
      throw error;
    }
  }

  sendAlert(message) {
    console.error("ALERT:", message);
    // Send to your monitoring service
  }
}

Handling UNKNOWN_ERROR

Critical: Never refund immediately on UNKNOWN_ERROR. Always wait 24 hours for resolution.

async function handleUnknownError(orderId, topupId) {
  // Mark for review
  await db.orders.update({
    where: { id: orderId },
    data: {
      status: "REVIEW_NEEDED",
      reviewReason: "UNKNOWN_ERROR from API",
      reviewScheduled: new Date(Date.now() + 24 * 60 * 60 * 1000),
    },
  });

  // Show message to user
  await notifyUser(orderId, {
    title: "Order Under Review",
    message:
      "Your order is being verified. Status will update within 24 hours.",
  });

  // Schedule automatic recheck
  await scheduleJob("recheck-unknown-error", {
    orderId,
    topupId,
    runAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
  });
}

Testing Error Scenarios

Use sandbox mode to test error handling:

// Test insufficient balance
// Set your sandbox balance very low

// Test validation errors
await sendTopUp({
  plan_code: 'INVALID_PLAN',
  MSSIDN: '123456789',     // Invalid format
  amount: -100             // Negative amount
});

// Test duplicate reference
const ref = 'test-duplicate-123';
await sendTopUp({ ref, ... });  // First request
await sendTopUp({ ref, ... });  // Should fail with DUPLICATED_REF

Quick Reference

Validate Early

Validate input client-side before API calls to catch errors early

Retry Smart

Use exponential backoff for 5xx errors, never retry 4xx errors

Log Context

Always include requestId and context in logs for debugging

User Feedback

Show clear, actionable error messages to users

Bill Payment errors

This section covers the Bill Payment endpoints under https://api.oneclickdz.com/v3/bills. They add the codes below to the key-level errors described above, which apply here too.

Bill Payment returns the same envelope as every other service — success, error.code, error.message, requestId — and every response also carries an X-Request-Id header.

Synchronous errors

These are returned by the request itself. This is the complete set.

Code	HTTP	Meaning	What to do
`MISSING_ACCESS_TOKEN`	401	No `X-Access-Token` header	Send the header
`INVALID_ACCESS_TOKEN`	401	The key was rejected	Check the key; do not retry unchanged
`IP_NOT_ALLOWED`	403	Your address is not on the key’s IP whitelist	Add it to the whitelist, or call from a whitelisted address
`API_DISABLED`	403	API access is switched off for this key	Contact us
`AUTH_UNAVAILABLE`	503	We could not verify the key in time	Retry after `Retry-After` — this is not a bad key
`ERR_VALIDATION`	400	The request does not match the schema	Fix the request; `details` lists every field
`INVALID_ACCOUNT`	400	The account identifier is not usable	Ask the customer to check their bill
`DUPLICATED_REF`	403	This `ref` is already in use for that partner	Look the `ref` up; never resend
`NOT_FOUND`	404	Unknown transaction, not payable, or not yours	Re-read the transaction
`BILL_ALREADY_PAID`	409	The bill has already been paid	Use the existing receipt
`PAYMENT_IN_PROGRESS`	409	Another payment for it is running	Poll the running one
`PAYLOAD_TOO_LARGE`	413	The request body is too large	Send a smaller body
`PARTNER_UNAVAILABLE`	503	The biller is unreachable or switched off	Retry later; nothing was charged
`SERVICE_UNAVAILABLE`	503	The bill service did not answer in time	The outcome is unknown — look the transaction up before resending
`INTERNAL_ERROR`	500	Something failed on our side	Read the transaction before retrying a write

AUTH_UNAVAILABLE carries a Retry-After: 5 header and nothing was started, so the same request can be sent again. PARTNER_UNAVAILABLE and SERVICE_UNAVAILABLE do not — back off on your side, and for SERVICE_UNAVAILABLE recover with GET /v3/bills/transactions/by-ref rather than resending.

Terminal errors

These never appear in a response body of their own. They appear inside a transaction’s error object, and only when its status is FAILED or REFUNDED.

Code	Message
`PAYMENT_DECLINED`	The payment was declined by the bank or partner portal.
`PARTNER_UNAVAILABLE`	The partner service is temporarily unavailable.
`INVALID_ACCOUNT`	The provided account identifier is invalid.
`BILL_ALREADY_PAID`	This bill has already been paid.

Branch on code, never on message.

Two rules that matter more than the rest

A foreign transaction is a 404, not a 403. A transaction that belongs to another partner — or to the other environment — is reported as not found, by design, so the API never confirms that someone else’s transaction exists. Treat 404 as “check the identifier and the key”, not as “access denied”.

UNKNOWN is not an error. It is a status meaning the outcome has not been confirmed yet, and it resolves on its own to SUCCESS or REFUNDED. While it lasts: never refund your customer, never resend the payment, and never show “payment failed”. Keep polling.

Where to go next

Bill Payment Overview

How the whole flow fits together

Status Polling

Handling UNKNOWN and REFUNDED

Get Transaction by ID

The transaction object and its statuses

Sandbox Testing

Reproduce each error on demand

Next Steps

Core Endpoints

Explore all endpoints

Response Format

Understanding API responses

​Error Response Structure

​HTTP Status Codes

​Common Error Codes

​MISSING_ACCESS_TOKEN

​INVALID_ACCESS_TOKEN / ERR_AUTH

​NO_BALANCE / INSUFFICIENT_BALANCE

​DUPLICATED_REF

​IP_BLOCKED

​IP_NOT_ALLOWED

​ERR_VALIDATION

​ERR_PHONE

​ERR_STOCK

​NOT_FOUND - Message: Resource not found - Cause: The requested

​RATE_LIMIT_EXCEEDED

​INTERNAL_SERVER_ERROR / INTERNAL_ERROR

​ERR_SERVICE

​Implementation Best Practices

​1. Always Check Success Field

​2. Handle Specific Error Codes

​3. Smart Retry Logic with Exponential Backoff

​4. User-Friendly Error Messages

​5. Log Request IDs

​Advanced Patterns

​Circuit Breaker Pattern

​Error Monitoring

​Handling UNKNOWN_ERROR

​Testing Error Scenarios

​Quick Reference

Validate Early

Retry Smart

Log Context

User Feedback

​Bill Payment errors

​Synchronous errors

​Terminal errors

​Two rules that matter more than the rest

​Where to go next

Bill Payment Overview

Status Polling

Get Transaction by ID

Sandbox Testing

​Next Steps

Core Endpoints

Response Format

Error Response Structure

HTTP Status Codes

Common Error Codes

MISSING_ACCESS_TOKEN

INVALID_ACCESS_TOKEN / ERR_AUTH

NO_BALANCE / INSUFFICIENT_BALANCE

DUPLICATED_REF

IP_BLOCKED

IP_NOT_ALLOWED

ERR_VALIDATION

ERR_PHONE

ERR_STOCK

NOT_FOUND - Message: Resource not found - Cause: The requested

RATE_LIMIT_EXCEEDED

INTERNAL_SERVER_ERROR / INTERNAL_ERROR

ERR_SERVICE

Implementation Best Practices

1. Always Check Success Field

2. Handle Specific Error Codes

3. Smart Retry Logic with Exponential Backoff

4. User-Friendly Error Messages

5. Log Request IDs

Advanced Patterns

Circuit Breaker Pattern

Error Monitoring

Handling UNKNOWN_ERROR

Testing Error Scenarios

Quick Reference

Bill Payment errors

Synchronous errors

Terminal errors

Two rules that matter more than the rest

Where to go next

Next Steps