v1.0

Error Codes

When an error occurs, the Vexutopia API returns a consistent error response format with details to help you understand and handle the issue.

Error Response Format

All errors follow this structure:

JSON
{
  "error": {
    "code": "invalid_request",
    "message": "The amount field is required",
    "param": "amount",
    "doc_url": "https://vexutopia.com/docs/errors#invalid_request"
  }
}
Error Object
ParameterTypeDescription
codestringA machine-readable error code
messagestringA human-readable description of the error
paramstringThe parameter that caused the error (if applicable)
doc_urlstringLink to documentation about this error

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

200
OK

Request succeeded

201
Created

Resource created successfully

400
Bad Request

Invalid request parameters or body

401
Unauthorized

Missing or invalid API key

403
Forbidden

API key lacks required permissions

404
Not Found

Requested resource does not exist

429
Too Many Requests

Rate limit exceeded. Slow down requests.

500
Internal Server Error

Something went wrong on our end

Error Codes

Common error codes you may encounter:

CodeDescription
unauthorizedNo API key provided
invalid_api_keyAPI key is invalid or has been revoked
invalid_requestRequest body or parameters are invalid
missing_parameterA required parameter is missing
invalid_parameterA parameter has an invalid value
resource_not_foundThe requested resource does not exist
payment_failedPayment was declined by the provider
insufficient_fundsCustomer has insufficient funds
card_declinedCard was declined
rate_limit_exceededToo many requests, please slow down
internal_errorAn unexpected error occurred

Handling Errors

Here's how to properly handle errors in your integration:

JavaScript
async function createPayment(amount, currency) {
  const response = await fetch('https://api.vexutopia.com/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer vex_test_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ amount, currency })
  });

  const data = await response.json();

  if (!response.ok) {
    // Handle the error based on the code
    switch (data.error.code) {
      case 'invalid_api_key':
        throw new Error('Check your API key configuration');
      case 'invalid_parameter':
        throw new Error(`Invalid ${data.error.param}: ${data.error.message}`);
      case 'payment_failed':
        throw new Error('Payment was declined, try a different method');
      case 'rate_limit_exceeded':
        // Wait and retry
        await new Promise(r => setTimeout(r, 1000));
        return createPayment(amount, currency);
      default:
        throw new Error(data.error.message);
    }
  }

  return data;
}

Rate Limiting

The API enforces rate limits to ensure fair usage. When you exceed the limit, you'll receive a 429 response.

Default Limits

  • Test mode: 100 requests per minute
  • Live mode: 1,000 requests per minute

Rate Limit Headers

Check these response headers to track your usage:

  • X-RateLimit-Limit: 1000
  • X-RateLimit-Remaining: 950
  • X-RateLimit-Reset: 1705663200

Need Help?

If you encounter persistent errors or need assistance, contact our support team at support@vexutopia.com with your request ID (found in the X-Request-Id header).