Skip to main content
The Kotani Pay API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
  • 2xx codes indicate success
  • 4xx codes indicate an error that failed given the information provided
  • 5xx codes indicate an error with Kotani Pay’s servers

​
Error Response Format

All error responses follow a consistent format: 
{
  "status": "error",
  "message": "A human-readable error message",
  "error_code": "SPECIFIC_ERROR_CODE",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Common Error Codes

CodeDescription
INVALID_API_KEYThe provided API key is invalid or expired
INSUFFICIENT_BALANCEInsufficient balance in the wallet
INVALID_PHONE_NUMBERThe phone number format is invalid
TRANSACTION_FAILEDThe transaction could not be processed
RATE_LIMITEDToo many requests - rate limit exceeded

​
Best Practices

  1. Always check the response status before processing the response body
  2. Implement retry logic for 5xx errors with exponential backoff
  3. Log error responses for debugging and monitoring
  4. Handle rate limiting by implementing proper backoff strategies