Error Handling

Errors that can be returned from the API and how to handle them.

HTTP Error Codes

Code	Meaning	What to Do?
400	Invalid request	Check the request body
401	Unauthorized	Check your API key
404	Not found	Check that the Session ID is correct and valid
422	Validation error	Check required fields
429	Rate limit	Wait a while, reduce requests
500	Server error	Contact the support team

Error Response Format

{
  "detail": "Session not found or expired"
}

Payment Errors

Errors that can be returned during a payment operation:

{
  "success": false,
  "order_id": "ORD-xxx",
  "status": "error",
  "message": "Insufficient balance"
}

Common Errors and Solutions

"Session not found or expired"

• Check that the Session ID is correct
• If more than 1 hour has passed since the session was created, create a new session

"Invalid merchant API key"

• Make sure the API key is correct
• Make sure your merchant account is active — if the problem persists, contact [email protected]

CORS Error

• Your site's domain must be added to the API's CORS settings
• http and https make a difference, make sure you're using the correct protocol

3D Secure Timeout

• The customer may have waited too long on the 3D Secure page
• Start a new payment attempt

Retry Strategy

async function payWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await makePayment(data);
      return result;
    } catch (error) {
      if (error.response?.status === 429) {
        await new Promise(r => setTimeout(r, 2000 * (i + 1)));
        continue;
      }
      if (error.response?.status >= 500) {
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Maximum retry limit reached");
}