> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kotanipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> HTTP status codes and error response format for the Kotani Pay API

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:**

```json theme={null}
{
  "success": true,
  "message": "Operation completed successfully",
  "data": {}
}
```

**Error:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

***

## Rate Limit Errors

When rate limited, the `data` field includes how long to wait:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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"
  }
}
```