Error Codes Reference

KisPay uses standard HTTP response codes to indicate the success or failure of API requests. This comprehensive guide helps you understand, identify, and handle errors that may occur during integration.

HTTP Status Codes

KisPay API returns standard HTTP status codes to indicate the general outcome of requests:

Some Error Response Format

All error responses follow a consistent JSON structure:

{
  "statusCode": 400,
  "message": "Invalid credentials",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Error Response Fields

• statusCode: HTTP status code (400, 401, 500, etc.)
• message: Human-readable error message describing what went wrong
• timestamp: ISO 8601 timestamp when the error occurred

Authentication Errors

Errors related to API authentication and authorization.

ERR_AUTH_001: Missing API Key

{
  "statusCode": 401,
  "message": "Unauthorized",
  "timestamp": "2025-10-24T06:18:32.600594464"
}

Cause: No API key provided in the Authorization header.

Solution: Include your API key in the request:

headers: {
  'x-api-key': 'YOUR_API_KEY'
}

ERR_AUTH_002: Invalid API Key

{
  "statusCode": 401,
  "message": "Unauthorized",
  "timestamp": "2025-10-24T06:18:32.600594464"
}

Cause: The provided API key format is incorrect or corrupted.

Solution: Verify your API key format. Production keys start with KPG_PROD- and test keys with KPG_TEST-.

ERR_AUTH_003: Expired API Key

{
  "statusCode": 401,
  "message": "Unauthorized",
  "timestamp": "2025-10-24T06:18:32.600594464"
}

Cause: Your API key has been revoked or expired.

Solution: Generate a new API key from your KisPay Merchant Dashboard.

ERR_AUTH_004: Unauthorized Access

{
  "statusCode": 403,
  "message": "Forbidden - You don't have permission to access this resource",
  "timestamp": "2025-10-24T06:18:32.600594464"
}

Cause: Your account doesn’t have the required permissions for this endpoint.

Solution: Contact KisPay support to verify your account permissions.

Validation Errors

Errors related to request data validation.

ERR_VAL_001: Missing Required Field

{
  "statusCode": 400,
  "message": "Missing required field",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: A required field is missing from the request body.

Solution: Ensure all required fields are included in your request.

ERR_VAL_002: Invalid Field Format

{
  "statusCode": 400,
  "message": "Invalid email address format",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Field value doesn’t match the expected format.

Solution: Verify the field format matches the API specification.

ERR_VAL_004: Invalid Phone Number

{
  "statusCode": 400,
  "message": "Invalid Phone number",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Phone number format is incorrect.

ERR_VAL_005: Invalid URL

{
  "statusCode": 400,
  "message": "successUrl must be a valid HTTPS URL",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Callback URL is not a valid HTTPS URL (required in production).

Solution: Ensure all callback URLs (successUrl, cancelUrl, errorUrl, redirectUrl) are valid HTTPS URLs in production.

Session Errors

Errors related to checkout sessions.

ERR_SESSION_001: Session Not Found

{
  "statusCode": 404,
  "message": "Checkout session not found",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: The requested session ID doesn’t exist or has been deleted.

Solution: Verify the session ID is correct. Sessions may expire after 24 hours.

ERR_SESSION_002: Session Expired

{
  "statusCode": 410,
  "message": "Checkout session has expired",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: The checkout session has expired.

Solution: Create a new checkout session. Sessions are valid for 24 hours.

ERR_SESSION_003: Session Already Used

{
  "statusCode": 409,
  "message": "Checkout session has already been used",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Attempting to reuse a session that has already processed a payment.

Solution: Create a new session for each transaction.

ERR_SESSION_004: Session Creation Failed

{
  "statusCode": 500,
  "message": "An error occurred while processing your request",
  "timestamp": "2025-10-24T06:23:13.295+00:00"
}

Cause: Internal error during session creation.

Solution: Retry the request. If the issue persists, contact support.

ERR_SESSION_005: Duplicate Order Number

{
  "statusCode": 409,
  "message": "Duplicate order number detected",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: The order number has already been used in a recent transaction.

Solution: Use unique order numbers for each transaction.

Payment Errors

Errors related to payment processing.

ERR_PAY_001: Payment Failed

{
  "statusCode": 402,
  "message": "Payment processing failed - Insufficient funds",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Payment was declined by the payment provider.

Common Reasons:

• Insufficient funds
• Invalid payment credentials
• Payment method not supported
• Account blocked

Solution: Ask the customer to:

• Check their account balance
• Verify payment credentials
• Try a different payment method
• Contact their payment provider

ERR_PAY_002: Payment Method Unavailable

{
  "statusCode": 503,
  "message": "Payment method temporarily unavailable - TeleBirr",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: The selected payment method is temporarily unavailable due to maintenance or technical issues.

Solution:

• Try a different payment method
• Retry after the estimated recovery time
• Check KisPay status page for updates

ERR_PAY_003: Payment Timeout

{
  "statusCode": 408,
  "message": "Payment request timed out",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Customer didn’t complete payment within the allowed time, or payment provider timeout.

Solution:

• Create a new checkout session
• Ask customer to complete payment promptly
• Check payment provider status

ERR_PAY_004: Payment Already Processed

{
  "statusCode": 409,
  "message": "Payment has already been processed",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: Attempting to process a payment that’s already been completed.

Solution: Check payment status before attempting to process again.

ERR_PAY_005: Invalid Payment Method

{
  "statusCode": 400,
  "message": "Invalid or unsupported payment method",
  "timestamp": "2025-10-24T06:21:19.716+00:00"
}

Cause: The specified payment method is not supported.

Supported Payment Methods:

• TeleBirr
• CBE Birr
• Awash Birr
• M-Pesa (coming soon)

Solution: Use a supported payment method.

Network & Connection Errors

Errors related to network connectivity and API communication.

ERR_NET_001: Connection Timeout

{
  "statusCode": 504,
  "message": "Gateway timeout - Connection timeout",
  "timestamp": "2025-10-24T06:23:13.295+00:00"
}

Cause: Request took too long to complete.

Solution:

• Retry the request with exponential backoff
• Check your internet connection
• Verify KisPay API status

ERR_NET_002: Network Error

{
  "statusCode": 503,
  "message": "Service unavailable - Network error occurred",
  "timestamp": "2025-10-24T06:23:13.295+00:00"
}

Cause: Network connectivity issue between your server and KisPay API.

Solution:

• Check your server’s internet connection
• Verify DNS resolution for api.kispay.et
• Check firewall settings

Need Help?

If you encounter an error not covered in this documentation:

• Email: developers@kispay.et