Errors

Kyren Pay uses conventional HTTP status codes to indicate the success or failure of an API request.

HTTP Status Codes

Status Code	Description
`200`	OK — Request succeeded
`201`	Created — Resource created successfully
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Missing or invalid API key
`403`	Forbidden — Insufficient permissions
`404`	Not Found — Resource does not exist
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end

Error Response Format

When an error occurs, the response body contains a JSON object with the following structure:

{
  "code": 400,
  "message": "Bad Request",
  "error": {
    "field": "productId",
    "reason": "Product ID is required"
  }
}

Field	Type	Description
`code`	integer	HTTP status code
`message`	string	A human-readable error message
`error.field`	string	The parameter that caused the error (if applicable)
`error.reason`	string	Detailed explanation of what went wrong

The error object is only present for validation errors (400). Other error types only include code and message.

Common Errors

400 Bad Request

Returned when the request body or parameters are invalid.

{
  "code": 400,
  "message": "Bad Request",
  "error": {
    "field": "price",
    "reason": "Price must be at least 0.01"
  }
}

401 Unauthorized

Returned when the API key is missing or invalid.

{
  "code": 401,
  "message": "Unauthorized"
}

404 Not Found

Returned when the requested resource does not exist.

{
  "code": 404,
  "message": "Not Found"
}

429 Too Many Requests

Returned when you exceed the API rate limit (100 requests per minute).

{
  "code": 429,
  "message": "Too Many Requests"
}

Implement exponential backoff in your integration to handle rate limiting gracefully.

Success Response Format

Successful responses always include code: 0 and message: "success":

{
  "code": 0,
  "message": "success",
  "data": {
    // Response data here
  }
}

For paginated endpoints, the data field contains items and pagination:

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 42,
      "totalPages": 3
    }
  }
}

Start Here

Dashboard Guide

Webhooks

Troubleshooting

Epay Migration

FAQ

References

HTTP Status Codes

Error Response Format

Common Errors

400 Bad Request

401 Unauthorized

404 Not Found

429 Too Many Requests

Success Response Format

​HTTP Status Codes

​Error Response Format

​Common Errors

​400 Bad Request

​401 Unauthorized

​404 Not Found

​429 Too Many Requests

​Success Response Format

HTTP Status Codes

Error Response Format

Common Errors

400 Bad Request

401 Unauthorized

404 Not Found

429 Too Many Requests

Success Response Format