Troubleshooting

Updated 9 July 2026

Common Issues

This page covers the most frequently encountered issues when integrating with Aimable. If your problem is not listed here, raise a support ticket.

Connection Problems

If you are unable to reach the Aimable API, check the following:

Verify that your network allows outbound HTTPS connections to your per-tenant gateway <your-tenant>.aimable.ai
Ensure you are using https:// (not http://) — all API traffic requires TLS
If you are behind a corporate firewall or proxy, confirm that <your-tenant>.aimable.ai is allowlisted

A quick connectivity test:

bash

curl -i https://<your-tenant>.aimable.ai/api/v1/models \
  -H "X-API-Key: $AIMABLE_API_KEY"

A 200 confirms connectivity and authentication. A 401 still means you reached Aimable — re-check your key. No response at all points to a network or DNS issue.

Authentication Errors

The most common authentication error is a 401 Unauthorized response:

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

To resolve this:

Confirm your API key is correct and has not been rotated or revoked
Check that the X-API-Key header is set to your key (ak.<key_id>.<secret>); Authorization: Bearer is only for human/JWT sessions, not API keys
Ensure there are no extra spaces or characters in the header value
Generate a new key from the dashboard if the issue persists

Rate Limiting

When you exceed your rate limit, the API returns a 429 Too Many Requests response:

json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Best practices for handling rate limits:

Implement exponential backoff with jitter for retries
Respect the Retry-After header value in 429 responses
Consider batching requests where the API supports it
Contact support if you consistently need higher throughput