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:
{
"error": {
"code": "invalid_request",
"message": "The amount field is required",
"param": "amount",
"doc_url": "https://vexutopia.com/docs/errors#invalid_request"
}
}| Parameter | Type | Description |
|---|---|---|
code | string | A machine-readable error code |
message | string | A human-readable description of the error |
param | string | The parameter that caused the error (if applicable) |
doc_url | string | Link to documentation about this error |
HTTP Status Codes
The API uses standard HTTP status codes to indicate success or failure:
Request succeeded
Resource created successfully
Invalid request parameters or body
Missing or invalid API key
API key lacks required permissions
Requested resource does not exist
Rate limit exceeded. Slow down requests.
Something went wrong on our end
Error Codes
Common error codes you may encounter:
| Code | Description |
|---|---|
unauthorized | No API key provided |
invalid_api_key | API key is invalid or has been revoked |
invalid_request | Request body or parameters are invalid |
missing_parameter | A required parameter is missing |
invalid_parameter | A parameter has an invalid value |
resource_not_found | The requested resource does not exist |
payment_failed | Payment was declined by the provider |
insufficient_funds | Customer has insufficient funds |
card_declined | Card was declined |
rate_limit_exceeded | Too many requests, please slow down |
internal_error | An unexpected error occurred |
Handling Errors
Here's how to properly handle errors in your integration:
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).