Skip to main content
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"
  }
}