Getting Started
Error Handling
Understanding RoxPay API error responses and status codes.
The RoxPay API uses standard HTTP status codes and returns structured error responses.
Error Response Format
{
"Message": "Description of what went wrong.",
"StatusCode": 400,
"Result": false,
"Errors": [
{
"Field": "Amount",
"Message": "Amount must be greater than 0."
}
]
}HTTP Status Codes
| Code | Meaning | Description |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
400 | Bad Request | Invalid parameters or validation error |
401 | Unauthorized | Missing or invalid authentication token |
403 | Forbidden | Valid token but insufficient permissions |
404 | Not Found | Resource does not exist |
409 | Conflict | Duplicate resource (e.g. same TransactionId) |
422 | Unprocessable | Business rule violation |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Error | Server-side error |
Common Validation Errors
Missing Required Fields
{
"Message": "Validation failed.",
"StatusCode": 400,
"Result": false,
"Errors": [
{ "Field": "Purpose", "Message": "This field is required." },
{ "Field": "Amount", "Message": "This field is required." }
]
}Invalid Field Values
{
"Message": "Validation failed.",
"StatusCode": 400,
"Result": false,
"Errors": [
{ "Field": "Currency", "Message": "Currency must be one of: EUR, USD, GBP, CHF, CAD, RON, JPY." },
{ "Field": "SuccessRedirectUrl", "Message": "URL must use HTTPS protocol." }
]
}Handling Errors in Code
async function createPaymentLink(payload) {
const response = await fetch('https://app.roxpay.eu/api/v4/payments/link', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const data = await response.json();
if (!data.Result) {
if (data.StatusCode === 401) {
await refreshToken();
return createPaymentLink(payload);
}
throw new ApiError(data.Message, data.Errors);
}
return data;
}Retry Strategy
- 429: Wait for the duration in
Retry-Afterheader, then retry - 500/502/503: Retry with exponential backoff (1s, 2s, 4s, max 30s)
- 400/401/403/404: Do not retry — fix the request