Troubleshooting Common Integration Issues

Problem: 401 Unauthorized on Every Request

Most common causes:

1. Token expired — Access tokens expire after 3,600 seconds. Implement token refresh logic
2. Wrong environment — Using a sandbox token against the production endpoint or vice versa
3. Whitespace in token — Ensure there are no leading/trailing spaces in the Authorization header value

# Debug: Check token expiry
import jwt
payload = jwt.decode(token, options={"verify_signature": False})
print(payload["exp"]) # Compare with current Unix timestamp

Problem: CORS Errors in Browser

Aelix APIs do not support browser-based (CORS) calls for security reasons. API credentials must never be exposed to browsers. Use a backend proxy instead:

// Your backend
app.get('/api/accounts', async (req, res) => {
const data = await aelixClient.banking.accounts.list();
res.json(data);
});

// Your frontend calls YOUR backend, not Aelix directly
const accounts = await fetch('/api/accounts').then(r => r.json());

Problem: 422 Unprocessable Entity

Check the details array in the error response — it specifies exactly which fields failed validation:

{
"error": {
"code": "VALIDATION_FAILED",
"details": [
{ "field": "amount", "issue": "must be a positive integer" },
{ "field": "currency", "issue": "must be an ISO 4217 code" }
]
}
}

Problem: Slow Response Times

1. Check the X-Response-Time header — if low, the latency is in your network, not the API
2. Enable connection keep-alive in your HTTP client to avoid TCP handshake overhead
3. Co-locate your application servers in the same region as the Aelix API (eu-west-1)
4. Use the fields query parameter to request only the fields your app needs

Problem: Webhook Delivery Not Received

1. Verify your endpoint is publicly accessible over HTTPS (not localhost)
2. Check the Webhook Delivery Log in the portal for response codes and retry history
3. Ensure your endpoint responds with HTTP 200 within 5 seconds
4. Confirm the webhook secret matches — a signature mismatch causes your endpoint to reject delivery