Common Error Codes

This documentation provides detailed information about common error codes and responses you may encounter when using the VikoTrust Payments API.

HTTP Status Codes

Overview

The API uses standard HTTP status codes to indicate the success or failure of requests. The response body will contain additional details about any errors.

Status Code Description When It Occurs
400 Bad Request Invalid parameters, missing required fields, or validation errors
401 Unauthorized Missing or invalid API key
403 Forbidden Account mismatch, unauthorized account, or IP not allowed
404 Not Found Merchant or transaction not found
429 Too Many Requests Rate limiting exceeded
500 Internal Server Error Unexpected server errors

Common API Error Responses

Authentication Errors

Error Message HTTP Status Description Solution
API key missing 401 No Authorization header provided or malformed Include a valid Authorization header with Bearer token
Invalid API key 401 The provided API key doesn't exist in our system Check your API key or generate a new one
Account number does not match API key owner 403 The accountNumber doesn't match the API key's owner Use the correct account number for your API key

Authorization Errors

Error Message HTTP Status Description Solution
Your account is not authorized 403 Merchant account verification is not completed Complete your account verification process
IP [client_ip] not allowed 403 The requesting IP is not whitelisted for this account Add your server IP to the allowed IPs list

Resource Not Found Errors

Error Message HTTP Status Description Solution
Merchant not found 404 The specified accountNumber doesn't exist Check your account number or contact support
Transaction not found 404 The specified transaction reference doesn't exist Verify your transaction reference

Validation Errors

Error Message HTTP Status Description Solution
Missing required fields 400 One or more required parameters are missing Include all required parameters in your request
Reference must not contain spaces 400 The reference parameter contains spaces Remove spaces from your reference value
Reference must be at most 15 characters 400 The reference parameter exceeds 15 characters Shorten your reference to 15 characters or less
Invalid msisdn format 400 The provided phone number format is invalid Provide the phone number in a valid format

Payment Processing Errors

Error Message HTTP Status Description Solution
Insufficient balance 400 Not enough funds to complete the transaction Top up your account balance
Too many requests. Please try again later. 429 Rate limit exceeded for payment requests Wait before making another request

Error Response Examples

Authentication Error Example

{
  "error": "Invalid API key"
}

Validation Error Example

{
  "error": "Reference must not contain spaces"
}

Payment Error Example

{
  "success": false,
  "message": "Insufficient funds",
  "error_code": "INSUFFICIENT_FUNDS"
}

Rate Limit Error Example

{
  "success": false,
  "message": "Too many requests. Please try again later."
}

Best Practices for Error Handling

Check HTTP Status Codes
Always verify the HTTP status code before processing response content to ensure proper error detection.
Implement Error Handling
Use try-catch blocks and proper error handling for all API requests to gracefully manage exceptions.
Log Errors for Debugging
Maintain detailed error logs to facilitate debugging and monitoring of API interactions.
User-Friendly Messages
Display clear, user-friendly error messages based on API responses while logging technical details.
Implement Retry Logic
For rate limit errors (429), implement retry mechanisms with exponential backoff strategies.
Validate Input Parameters
Validate all request parameters before API calls to minimize errors and improve efficiency.
Security Notes