---
updatedAt: 2026-09-23T02:17:54.000Z
agentTools:
  projectIndex: https://docs.kyshi.co/llms.txt
---

# Errors

Kyshi uses conventional HTTP status codes and a consistent JSON response envelope.

Use the HTTP status code for transport-level handling and the `status`, `message`, and `data` fields for application-level handling.

# HTTP Status Code Summary

|               Method               |                                                                                Description                                                                                |
| :--------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|              200 - OK              |                                                                       Everything worked as expected.                                                                      |
|            201 - Created           |                                                      Everything worked as expected and a new record has been created                                                      |
|          400 - Bad Request         |                                                  The request was unacceptable, often due to missing a required parameter.                                                 |
|         401 - Unauthorized         |                                                                         No valid API key provided.                                                                        |
|           403 - Forbidden          |                                                        The API key doesn't have permissions to perform the request.                                                       |
|           404 - Not Found          |                                                                   The requested resource doesn't exist.                                                                   |
|     422 - Unprocessable Entity     | This means we understands the content type of the request body, and the syntax of the request body is correct however we're unable to process the contained instructions. |
| 500, 502, 503, 504 - Server Errors |                                                                    Something went wrong on Kyshi's end.                                                                   |

# Error Response Shape

```Text JSON
{
  "status": false,
  "message": "Unsupported Merchant Currency",
  "code": 422,
  "data": {}
}
```

# Integration Advice

* Treat `400` errors as request-shape issues: missing fields, invalid enums, or wrong data types.
* Treat `401` errors as key or environment issues.
* Treat `404` errors as ID/reference/mode mismatches.
* Treat `422` errors as business-rule failures, such as unsupported currency or insufficient balance.
* Retry `5xx` errors only when the operation is safe to retry or when you supplied your own unique reference.