Kiotapay API Error Documentation

Welcome to the Kiotapay API Error Documentation. This guide outlines the various error responses you may encounter when integrating with our API. Each error is accompanied by a code, description, and potential solutions to help you debug and resolve issues quickly.

Error Format

All API responses for errors adhere to the following JSON format:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "string"
  }
}

Field	Type	Description
`errorCode`	string	A unique error code identifying the issue.
`message`	string	A short description of the error.
`details`	string	Additional details about the error, if available.
`statusCode`	string	A HTTP status code.

Error Codes

The following sections categorize error codes by their type.

1. Authentication & Authorization Errors

These errors occur when authentication or authorization fails.

Code	HTTP Status	Message	Description	Potential Solution
`AUTH_INVALID_TOKEN`	401	Invalid authentication token	The provided token is expired or invalid.	Refresh or generate a new token.
`AUTH_MISSING_TOKEN`	401	Authentication token missing	No authentication token was provided.	Ensure the `Authorization` header contains a valid token.
`AUTH_FORBIDDEN`	403	Access denied	You do not have the required permissions to access this resource.	Check your user roles and permissions.

2. Request Errors

These errors are related to malformed or invalid API requests.

Code	HTTP Status	Message	Description	Potential Solution
`REQ_BAD_REQUEST`	400	Bad request	The request is invalid or improperly formatted.	Verify the request payload and parameters.
`REQ_MISSING_FIELD`	400	Missing required field	A required field is missing in the request.	Check the API documentation for required fields.
`REQ_INVALID_FIELD`	400	Invalid field value	A field value is invalid or incorrectly formatted.	Ensure all field values conform to the expected data types and formats.

3. Resource Errors

These errors occur when accessing resources that do not exist or are unavailable.

Code	HTTP Status	Message	Description	Potential Solution
`RESOURCE_NOT_FOUND`	404	Resource not found	The requested resource does not exist.	Check the resource identifier or endpoint URL.
`RESOURCE_LOCKED`	423	Resource is locked	The resource is temporarily locked.	Retry after some time or contact support.

4. Payment Errors

These errors occur during payment operations.

Code	HTTP Status	Message	Description	Potential Solution
`PAYMENT_FAILED`	402	Payment failed	The payment process could not be completed.	Check payment details and retry.
`PAYMENT_LIMIT_EXCEEDED`	403	Payment limit exceeded	The payment exceeds the allowed limit.	Adjust the payment amount or contact support.
`INSUFFICIENT_FUNDS`	402	Insufficient funds	The account has insufficient funds.	Ensure the account has sufficient balance.

5. Server Errors

These errors indicate issues on the Kiotapay platform.

Code	HTTP Status	Message	Description	Potential Solution
`SERVER_ERROR`	500	Internal server error	An unexpected error occurred on the server.	Retry the request or contact support.
`SERVICE_UNAVAILABLE`	503	Service unavailable	The service is temporarily unavailable.	Retry after a short delay.
`TIMEOUT_ERROR`	504	Request timeout	The request took too long to process.	Optimize the request or retry later.

HTTP Status Codes Overview

The following table summarizes the HTTP status codes used by the Kiotapay API:

HTTP Status Code	Description
200	OK - The request was successful.
201	Created - A new resource was successfully created.
400	Bad Request - The request was invalid.
401	Unauthorized - Authentication is required.
403	Forbidden - Access is denied.
404	Not Found - The requested resource does not exist.
500	Internal Server Error - A server error occurred.
503	Service Unavailable - The server is temporarily unavailable.

Handling Errors

When an error occurs, follow these steps to diagnose and resolve it:

Check the error code and message: Refer to the error tables above for guidance.
Review the request: Ensure the request payload, headers, and parameters are correct.
Consult the API documentation: Verify that you are using the correct endpoints and request formats.
Retry if applicable: For temporary errors (e.g., SERVICE_UNAVAILABLE), retry the request after a short delay.
Contact support: If the issue persists, reach out to Kiotapay support with the error details.

Contact Support

For further assistance, please contact Kiotapay Support or visit our Developer Portal.

This documentation is designed to help you effectively integrate with the Kiotapay API. By following these guidelines, you can handle errors efficiently and minimize downtime for your application.

Authentication

Checkout

Mobile Money (B2C)

Mobile Money (C2B & STK Push)

Business Payments (Till)

Business Payments (Paybill)

Bank Collections

Bank Payouts

Virtual Accounts

Errors

Error Format

Error Codes

1. Authentication & Authorization Errors

2. Request Errors

3. Resource Errors

4. Payment Errors

5. Server Errors

HTTP Status Codes Overview

Handling Errors

Contact Support

​Error Format

​Error Codes

​1. Authentication & Authorization Errors

​2. Request Errors

​3. Resource Errors

​4. Payment Errors

​5. Server Errors

​HTTP Status Codes Overview

​Handling Errors

​Contact Support

Error Format

Error Codes

1. Authentication & Authorization Errors

2. Request Errors

3. Resource Errors

4. Payment Errors

5. Server Errors

HTTP Status Codes Overview

Handling Errors

Contact Support