Error Handling

Understand the error response format and common error codes to handle failures gracefully.

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Codes

Code	HTTP	Description
`UNAUTHORIZED`	401	Invalid or missing API keys
`INVALID_REQUEST`	400	Missing or invalid parameters
`BILLING_REQUIRED`	403	Complete billing setup in dashboard
`BILLING_SUSPENDED`	403	Account suspended for non-payment
`GROUP_NOT_FOUND`	404	Group not found or inactive
`TRANSACTION_NOT_FOUND`	404	Payment ID not found
`ALREADY_COMPLETED`	400	Cannot cancel completed payment
`NO_AVAILABLE_SAFESITE`	503	No SafeSites available for processing
`STRIPE_ERROR`	502	Error communicating with payment processor
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Something went wrong

Handling Errors

Always check the success field in the response and handle errors appropriately:

javascript

async function createPayment(amount, currency) {
  const response = await fetch('https://pay.ultrapay.cc/api/v1/payments/create', {
    method: 'POST',
    headers: {
      'X-Public-Key': process.env.ULTRAPAY_PUBLIC_KEY,
      'X-Secret-Key': process.env.ULTRAPAY_SECRET_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount,
      currency,
      successUrl: 'https://yoursite.com/success',
      cancelUrl: 'https://yoursite.com/cancel',
    }),
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'UNAUTHORIZED':
        throw new Error('Invalid API keys. Check your configuration.');

      case 'INVALID_REQUEST':
        throw new Error(`Invalid request: ${data.error.message}`);

      case 'NO_AVAILABLE_SAFESITE':
        throw new Error('Payment processing temporarily unavailable.');

      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await new Promise(resolve => setTimeout(resolve, 1000));
        return createPayment(amount, currency);

      default:
        throw new Error(data.error.message);
    }
  }

  return data.data;
}

Rate Limits

Limit	Value
Requests per minute	100
Concurrent connections	50

Exceeded limits return 429 RATE_LIMIT_EXCEEDED. Implement exponential backoff for retries.