Skip to main content
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"
  }
}
FieldTypeDescription
errorCodestringA unique error code identifying the issue.
messagestringA short description of the error.
detailsstringAdditional details about the error, if available.
statusCodestringA 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.
CodeHTTP StatusMessageDescriptionPotential Solution
AUTH_INVALID_TOKEN401Invalid authentication tokenThe provided token is expired or invalid.Refresh or generate a new token.
AUTH_MISSING_TOKEN401Authentication token missingNo authentication token was provided.Ensure the Authorization header contains a valid token.
AUTH_FORBIDDEN403Access deniedYou 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.
CodeHTTP StatusMessageDescriptionPotential Solution
REQ_BAD_REQUEST400Bad requestThe request is invalid or improperly formatted.Verify the request payload and parameters.
REQ_MISSING_FIELD400Missing required fieldA required field is missing in the request.Check the API documentation for required fields.
REQ_INVALID_FIELD400Invalid field valueA 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.
CodeHTTP StatusMessageDescriptionPotential Solution
RESOURCE_NOT_FOUND404Resource not foundThe requested resource does not exist.Check the resource identifier or endpoint URL.
RESOURCE_LOCKED423Resource is lockedThe resource is temporarily locked.Retry after some time or contact support.

​
4. Payment Errors

These errors occur during payment operations.
CodeHTTP StatusMessageDescriptionPotential Solution
PAYMENT_FAILED402Payment failedThe payment process could not be completed.Check payment details and retry.
PAYMENT_LIMIT_EXCEEDED403Payment limit exceededThe payment exceeds the allowed limit.Adjust the payment amount or contact support.
INSUFFICIENT_FUNDS402Insufficient fundsThe account has insufficient funds.Ensure the account has sufficient balance.

​
5. Server Errors

These errors indicate issues on the Kiotapay platform.
CodeHTTP StatusMessageDescriptionPotential Solution
SERVER_ERROR500Internal server errorAn unexpected error occurred on the server.Retry the request or contact support.
SERVICE_UNAVAILABLE503Service unavailableThe service is temporarily unavailable.Retry after a short delay.
TIMEOUT_ERROR504Request timeoutThe 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 CodeDescription
200OK - The request was successful.
201Created - A new resource was successfully created.
400Bad Request - The request was invalid.
401Unauthorized - Authentication is required.
403Forbidden - Access is denied.
404Not Found - The requested resource does not exist.
500Internal Server Error - A server error occurred.
503Service Unavailable - The server is temporarily unavailable.

​
Handling Errors

When an error occurs, follow these steps to diagnose and resolve it:
  1. Check the error code and message: Refer to the error tables above for guidance.
  2. Review the request: Ensure the request payload, headers, and parameters are correct.
  3. Consult the API documentation: Verify that you are using the correct endpoints and request formats.
  4. Retry if applicable: For temporary errors (e.g., SERVICE_UNAVAILABLE), retry the request after a short delay.
  5. 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.