1. [    Home ](/)
2. [Guides](/guides)
3. [Best Practices](/guides?category=29)
4. Handling Errors and Retries
 
 intermediate Best Practices      15 min       3 steps      10 min read  

# Handling Errors and Retries

  A  admin  April 15, 2026  

 

 

       

 

 

 

 

 ##     Prerequisites 

 

 

 

 

 ## On this page

  
  3 steps total 

 [    Back to top ](#main-content) 

 ## 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](https://aelix.digitalapi.ai/docs/errors#INVALID_ACCOUNT)"  
 }  
}

## HTTP Status Code Reference

StatusCodeMeaning400BAD\_REQUESTMissing or invalid request parameters401UNAUTHORIZEDInvalid or expired access token403FORBIDDENToken lacks required scope404NOT\_FOUNDResource does not exist409CONFLICTDuplicate resource or state conflict422UNPROCESSABLEValidation failed (see errors array)429RATE\_LIMITEDToo many requests — see Retry-After header500SERVER\_ERRORInternal error — safe to retry with back-off503SERVICE\_UNAVAILABLETemporary outage — retry with back-off## 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



 

 

 

 ### Tags

Tags

[Error Handling](/taxonomy/term/43)

[REST](/taxonomy/term/36)