Errors
Every error code the Kiotapay API can return, what causes it, and how to resolve it.
This page catalogues the error responses you may encounter when integrating with the Kiotapay API. Each entry lists the code, the HTTP status it arrives with, and what to do about it.
Error format
Errors are returned as a flat JSON object:
{
"code": "AUTH_ERROR",
"message": "Please check your API credentials",
"statusCode": 400,
"timestamp": "2026-08-12T15:54:16.480380445"
}| Field | Type | Description |
|---|---|---|
code | string | A unique error code identifying the issue. |
message | string | A short, human-readable description of the error. |
statusCode | integer | The HTTP status code, repeated in the body. |
timestamp | string | Server time the error was produced, ISO 8601. |
Codes below are not yet confirmed against the live API
The envelope above is real — it is an actual response from
api.kiotapay.co. The code catalogue below is not: it was inherited from
the previous documentation, which described a different envelope again
(errorCode / nested error object) and has never been reconciled with what
the API returns.
A live authentication failure returns AUTH_ERROR with status 400, where
this page documents AUTH_INVALID_TOKEN with 401. Treat the tables below
as indicative until they have been checked endpoint by endpoint, and always
branch on statusCode plus code as returned, not on the names here.
Authentication and authorization
Returned when authentication or authorization fails.
| Code | Status | Message | Cause | Resolution |
|---|---|---|---|---|
AUTH_INVALID_TOKEN | 401 | Invalid authentication token | The provided token is expired or invalid. | Request a new token from /api/v1/get-token. |
AUTH_MISSING_TOKEN | 401 | Authentication token missing | No authentication token was provided. | Ensure the Authorization header contains a valid token. |
AUTH_FORBIDDEN | 403 | Access denied | You do not have the required permissions for this resource. | Check your user roles and permissions. |
Access tokens expire after five minutes. If you see AUTH_INVALID_TOKEN on a
long-running job, refresh the token rather than retrying with the old one.
Request errors
Returned for malformed or invalid requests.
| Code | Status | Message | Cause | Resolution |
|---|---|---|---|---|
REQ_BAD_REQUEST | 400 | Bad request | The request is invalid or improperly formatted. | Verify the request payload and parameters. |
REQ_MISSING_FIELD | 400 | Missing required field | A required field is missing from the request. | Check the endpoint reference for required fields. |
REQ_INVALID_FIELD | 400 | Invalid field value | A field value is invalid or incorrectly formatted. | Ensure all field values conform to the expected data types and formats. |
Most REQ_MISSING_FIELD errors on payouts come from currency-conditional
fields — see the
send money reference for which fields each
currency requires.
Resource errors
Returned when a resource does not exist or is unavailable.
| Code | Status | Message | Cause | Resolution |
|---|---|---|---|---|
RESOURCE_NOT_FOUND | 404 | Resource not found | The requested resource does not exist. | Check the resource identifier or endpoint URL. |
RESOURCE_LOCKED | 423 | Resource is locked | The resource is temporarily locked. | Retry after a delay, or contact support. |
Payment errors
Returned during payment operations.
| Code | Status | Message | Cause | Resolution |
|---|---|---|---|---|
PAYMENT_FAILED | 402 | Payment failed | The payment process could not be completed. | Check payment details and retry. |
PAYMENT_LIMIT_EXCEEDED | 403 | Payment limit exceeded | The payment exceeds the allowed limit. | Adjust the payment amount or contact support. |
INSUFFICIENT_FUNDS | 402 | Insufficient funds | The account has insufficient funds. | Ensure the account has sufficient balance. |
Server errors
Returned when something goes wrong on the Kiotapay platform.
| Code | Status | Message | Cause | Resolution |
|---|---|---|---|---|
SERVER_ERROR | 500 | Internal server error | An unexpected error occurred on the server. | Retry the request or contact support. |
SERVICE_UNAVAILABLE | 503 | Service unavailable | The service is temporarily unavailable. | Retry after a short delay. |
TIMEOUT_ERROR | 504 | Request timeout | The request took too long to process. | Retry later. |
Server errors are safe to retry with exponential backoff. Do not retry a
4xx without changing the request — it will fail identically.
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | OK — the request was successful. |
| 201 | Created — a new resource was successfully created. |
| 400 | Bad Request — the request was invalid. |
| 401 | Unauthorized — authentication is required. |
| 403 | Forbidden — access is denied. |
| 404 | Not Found — the requested resource does not exist. |
| 500 | Internal Server Error — a server error occurred. |
| 503 | Service Unavailable — the server is temporarily unavailable. |
Handling errors
Check the code and message
Look the code up in the tables above. The message field describes what failed;
details narrows it to a specific field where available.
Review the request
Confirm the payload, headers and query parameters match the endpoint reference.
A surprising number of failures are a missing Authorization header or a
callbackUrl that is not publicly reachable.
Retry only what is retryable
SERVICE_UNAVAILABLE, TIMEOUT_ERROR and SERVER_ERROR are transient — retry
with backoff. Everything in the 4xx range needs the request itself to change.
Contact support
If the issue persists, email
apps@kiotapay.com with the error code, the
requestId if you have one, and the approximate time of the request.