Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kotanipay.com/llms.txt

Use this file to discover all available pages before exploring further.

The Kotani Pay API uses standard HTTP status codes. 2xx means success, 4xx means the request was rejected, 5xx means something failed on the server.

​
Response Envelope

All responses — success and error — follow a consistent envelope. Success: 
{
  "success": true,
  "message": "Operation completed successfully",
  "data": { }
}
Error: 
{
  "success": false,
  "message": "Descriptive error message",
  "error_code": 400,
  "data": { }
}
The error_code field mirrors the HTTP status code. For validation failures, data.errors contains the individual field messages: 
{
  "success": false,
  "message": "Validation failed: amount must be a positive number, customerKey should not be empty",
  "error_code": 400,
  "data": {
    "errors": [
      "amount must be a positive number",
      "customerKey should not be empty"
    ]
  }
}

​
Status Codes

StatusMeaning
200Success
400Bad request — invalid parameters or missing required fields
401Unauthorized — API key or JWT is missing or invalid
403Forbidden — key is valid but lacks permission, or the resource is not accessible
404Resource not found
429Rate limit exceeded
500Internal server error — contact support if it persists

​
Rate Limit Errors

When rate limited, the data field includes how long to wait: 
{
  "success": false,
  "message": "Too many requests. You have exceeded the limit of 60 requests per 60 seconds. Please wait before trying again.",
  "error_code": 429,
  "data": {
    "retryAfter": 60
  }
}

​
Customer Suspension

If a customer_key belongs to a suspended customer, the request returns 403: 
{
  "success": false,
  "message": "Customer cust_abc123 is temporarily suspended until 2025-01-01 12:00:00 UTC and cannot initiate transactions. Please contact support to resolve the customer's status.",
  "error_code": 403,
  "data": {
    "bannedUntil": "2025-01-01T12:00:00Z"
  }
}