# Error Codes


> Understand Chiwa Pay API error responses and codes.

Canonical: https://docs.chiwapay.com/errors

When a request fails, the API returns an `error` object.

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "secret key is invalid or revoked"
  }
}
```

## Public API

| HTTP | Code | Description |
| --- | --- | --- |
| `400` | `invalid_json` | Body is not valid JSON. |
| `400` | `invalid_amount` | Amount is invalid. |
| `400` | `invalid_bulk_size` | Bulk item count is invalid. |
| `400` | `unsupported_payment_method` | Payment method is not supported. |
| `400` | `payment_create_failed` | Transaction could not be created. |
| `400` | `payment_cancel_failed` | Transaction could not be cancelled. |
| `400` | `payment_refund_failed` | Transaction could not be refunded. |
| `401` | `invalid_api_key` | Secret key is missing, invalid, or revoked. |
| `403` | `merchant_not_approved` | Merchant is not active. |
| `403` | `api_key_ip_not_allowed` | Request IP is not in the API key allowlist. |
| `404` | `not_found` | Resource was not found. |
| `429` | `rate_limited` | Rate limit exceeded. |
| `500` | `server_error` | Request could not be processed. |

## Rate Limit

The API applies rate limits to keep the service stable.
If you receive `429`, wait briefly before sending the next request.

## Retry

| Condition | Retry |
| --- | --- |
| Timeout | Yes, use the same request. |
| `500` | Yes, after a delay. |
| `400`, `401`, `403`, `404` | No. Fix the request or merchant status. |
| `429` | Yes, after waiting for the next rate-limit window. |