Live Pay

LivePay

Live Pay LivePay

Error Handling & Common Error Codes

Comprehensive guide to handling errors for both Deposit and Withdraw APIs

Error Handling Overview

The LivePay API uses standard HTTP status codes and provides detailed error messages for both Deposit and Withdraw endpoints.

Common vs Specific Errors

Authentication, validation, and network errors are common to both APIs, while amount limits and balance checks differ.

Response Format

Success Response

{
    "status": "success",
    "message": "Transaction completed successfully",
    "phone": "256702069536",
    "payment_method": "mtnmomo",
    "transaction_id": "TXN123456789",
    "reference_id": "REF123456",
    "amount": 5000,
    "charge_amount": 50,
    "new_balance": 14950
}

Error Response

{
    "status": "error",
    "message": "Invalid phone number provided"
}

HTTP Status Codes

Code Status Description
200 OK Request successful
201 Created Transaction created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing authentication
405 Method Not Allowed Invalid HTTP method used

Common Errors (Both APIs)

Authentication Errors

Invalid Secret Api key

Bearer token is invalid or expired

Missing or invalid Authorization header

Authorization header missing or malformed

Invalid user public key

Public API key doesn't match user account

Api access is turned off by user

User has disabled API access

Validation Errors

Phone number body is required

Phone field missing in request

phone number must contain only digits

Phone contains invalid characters

Invalid phone number provided

Phone not supported by networks

Duplicate reference detected

Reference ID already exists

API-Specific Errors

Deposit-Specific Errors

amount can't be less than 500.00 UGX

Minimum deposit amount violation

amount can't be greater than 5,000,000.00 UGX

Maximum deposit amount exceeded

API access is turned off please contact the admin

Global deposit API status disabled

Withdraw-Specific Errors

amount can't be less than 500.00 UGX

Minimum withdrawal amount violation

amount can't be greater than 5,000,000.00 UGX

Maximum withdrawal amount exceeded

Insufficient funds

User balance too low for withdrawal

Withdrawals temporarily disabled. Contact admin

Global withdraw API status disabled

Error Handling Guide

1

Check HTTP Status Code

Verify status code before parsing response body

2

Parse Error Message

Read the message field for specific details

3

Implement Retry Logic

Use exponential backoff for network errors

4

Validate Input Data

Pre-validate phone, amount, and reference ID

Best Practices

Validate Inputs

Always validate phone numbers, amounts, and reference IDs before API calls

Implement Retries

Use exponential backoff for network and server errors (5xx status codes)

Monitor Webhooks

Set up webhook endpoints to receive real-time transaction status updates