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
`409`	Conflict — Resource state or idempotency conflict
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end
`503`	Service Unavailable — Upstream service error

Error Response Format

Application errors handled by the API use this JSON structure. Authentication middleware and proxy errors may have an empty or different body; check the HTTP status before parsing JSON.

{
  "code": 40001,
  "message": "Validation failed",
  "error": {
    "field": "productId",
    "reason": "Product ID is required"
  }
}

Field	Type	Description
`code`	integer	Application error code; different from the HTTP status
`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

error is optional. It is included when a field detail is available; field and reason may also be omitted independently. Do not depend on exact message text.

Application Error Codes

Code	Meaning
`40001`	Invalid request or validation failure
`40101`	Application-level unauthorized error
`40102`	Token expired
`40103`	Invalid API key
`40301`	Forbidden
`40401`	Resource not found
`40901`	Conflict
`40902`	Idempotency conflict
`42901`	Rate limit exceeded
`50001`	Internal server error
`50002`	External service error (HTTP `503`)
`60006`	Product not found
`60007`	Checkout expired
`60008`	Order not found

These codes identify the error condition. Business errors can use HTTP 400; do not infer the HTTP status from the first digits of code.

Common Errors

400 Bad Request

Returned when the request body or parameters are invalid.

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

401 Unauthorized

Returned when the API key is missing or rejected. The authentication entrypoint does not guarantee a JSON body. If an application-level unauthorized error returns JSON, its code is 40101.

404 Not Found

Returned when the requested resource does not exist.

{
  "code": 40401,
  "message": "Resource not found"
}

429 Too Many Requests

Returned when a configured rate limit is exceeded. Defaults are 100 requests per minute per IP for general API requests and 60 checkout creations per minute per authenticated merchant for POST /v1/checkouts. These limits are configurable and are not a guaranteed production quota.

{
  "code": 42901,
  "message": "Rate limit exceeded. Try again later."
}

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

Success Response Format

Public merchant JSON API success responses include code: 0 and message: "success". Epay compatibility responses and file downloads follow their endpoint-specific formats.

{
  "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

System Integrations

FAQ

References

HTTP Status Codes

Error Response Format

Application Error Codes

Common Errors

400 Bad Request

401 Unauthorized

404 Not Found

429 Too Many Requests

Success Response Format

​HTTP Status Codes

​Error Response Format

​Application Error Codes

​Common Errors

​400 Bad Request

​401 Unauthorized

​404 Not Found

​429 Too Many Requests

​Success Response Format

HTTP Status Codes

Error Response Format

Application Error Codes

Common Errors

400 Bad Request

401 Unauthorized

404 Not Found

429 Too Many Requests

Success Response Format