RoxPay API
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

Error Response
{
  "Message": "Description of what went wrong.",
  "StatusCode": 400,
  "Result": false,
  "Errors": [
    {
      "Field": "Amount",
      "Message": "Amount must be greater than 0."
    }
  ]
}

HTTP Status Codes

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid parameters or validation error
401UnauthorizedMissing or invalid authentication token
403ForbiddenValid token but insufficient permissions
404Not FoundResource does not exist
409ConflictDuplicate resource (e.g. same TransactionId)
422UnprocessableBusiness rule violation
429Too Many RequestsRate limit exceeded
500Internal ErrorServer-side error

Common Validation Errors

Missing Required Fields

400 Bad Request
{
  "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

400 Bad Request
{
  "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

error-handling.js
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-After header, then retry
  • 500/502/503: Retry with exponential backoff (1s, 2s, 4s, max 30s)
  • 400/401/403/404: Do not retry — fix the request

On this page