Handling Errors and Retries

Understanding Error Responses

All Aelix APIs return errors in a consistent JSON envelope, making it straightforward to parse and handle them programmatically:

{
"error": {
"code": "INVALID_ACCOUNT",
"message": "The specified account ID does not exist or you do not have access.",
"trace_id": "trc_9f3a2b1c",
"documentation_url": "https://aelix.digitalapi.ai/docs/errors#INVALID_ACCOUNT"
}
}

HTTP Status Code Reference

Implementing Exponential Back-off

For 429 and 5xx responses, implement retry logic with randomised jitter to avoid thundering-herd problems:

function callWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, options);

if (response.ok) return response.json();

if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || 2 ** attempt;
await sleep(retryAfter * 1000);
continue;
}

if (response.status >= 500) {
const delay = (2 ** attempt) * 1000 + Math.random() * 500;
await sleep(delay);
continue;
}

// 4xx errors — don't retry
const error = await response.json();
throw new Error(error.error.message);
}
throw new Error('Max retries exceeded');
}

Idempotency Keys

For POST requests that modify state (payments, transfers), always include an Idempotency-Key header. This ensures that if you retry due to a network timeout, the operation is only executed once:

POST /v1/payments
Idempotency-Key: pay_20250415_abc123
Content-Type: application/json