Skip to main content

Error Handling

Overview​

Proper error handling is crucial when integrating with the K2 Telecom USSD API. This guide covers all possible error responses and how to handle them effectively.

Error Response Format​

All error responses follow a consistent JSON format:

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "timestamp": "2024-01-15T10:30:00Z"
}

HTTP Status Codes​

2xx Success​

  • 200 OK - Request successful
  • 201 Created - Resource created successfully

4xx Client Errors​

  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Invalid or missing authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded

5xx Server Errors​

  • 500 Internal Server Error - Server error
  • 502 Bad Gateway - Gateway error
  • 503 Service Unavailable - Service temporarily unavailable

Common Error Codes​

Authentication Errors​

401 Unauthorized​

{
  "success": false,
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid API key or secret provided",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Check your API key and secret are correct and properly formatted.

403 Forbidden​

{
  "success": false,
  "error": "API_KEY_DISABLED",
  "message": "API key has been disabled or expired",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Contact support to reactivate your API key.

Validation Errors​

400 Bad Request​

{
  "success": false,
  "error": "INVALID_PHONE_NUMBER",
  "message": "Phone number format is invalid. Use format: +256XXXXXXXXX",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Ensure phone numbers are in the correct format (+256XXXXXXXXX).

{
  "success": false,
  "error": "INVALID_AMOUNT",
  "message": "Amount must be greater than 0 and less than 1000000",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Check that amounts are within valid ranges.

Rate Limiting​

429 Too Many Requests​

{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Limit: 100 requests per minute",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Implement exponential backoff and retry logic.

Session Errors​

404 Not Found​

{
  "success": false,
  "error": "SESSION_NOT_FOUND",
  "message": "USSD session not found or expired",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Create a new session or check session ID validity.

Transaction Errors​

{
  "success": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Insufficient balance to complete transaction",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Check account balance before initiating transactions.

{
  "success": false,
  "error": "TRANSACTION_FAILED",
  "message": "Transaction processing failed. Please try again",
  "timestamp": "2024-01-15T10:30:00Z"
}

Solution: Retry the transaction or contact support if persistent.

Best Practices for Error Handling​

1. Always Check Response Status​

if (!response.success) {
  console.error('API Error:', response.error, response.message);
  // Handle error appropriately
}

2. Implement Retry Logic​

const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }
      throw error;
    }
  }
};

3. Log Errors Appropriately​

const handleApiError = (error) => {
  console.error('API Error:', {
    code: error.error,
    message: error.message,
    timestamp: error.timestamp
  });
  
  // Send to monitoring service
  // Notify administrators if critical
};

4. User-Friendly Error Messages​

const getUserFriendlyMessage = (errorCode) => {
  const messages = {
    'INVALID_CREDENTIALS': 'Authentication failed. Please check your credentials.',
    'INSUFFICIENT_BALANCE': 'Insufficient balance to complete this transaction.',
    'RATE_LIMIT_EXCEEDED': 'Too many requests. Please try again in a moment.',
    'SESSION_NOT_FOUND': 'Session expired. Please start a new session.'
  };
  
  return messages[errorCode] || 'An unexpected error occurred. Please try again.';
};

Testing Error Scenarios​

Test Invalid Credentials​

curl -X GET https://www.k2-ussd-api.devlorde.xyz/data/collection \
  -H "x-api-key: invalid_key" \
  -H "x-api-secret: invalid_secret"

Test Rate Limiting​

# Make multiple rapid requests to trigger rate limiting
for i in {1..110}; do
  curl -X GET https://www.k2-ussd-api.devlorde.xyz/data/collection \
    -H "x-api-key: your_key" \
    -H "x-api-secret: your_secret"
done

Support​

If you encounter persistent errors or need assistance:

  • Email: support@k2telecom.ug
  • Phone: +256 708 730001
  • Response Time: Within 24 hours during business days