Troubleshooting

Common Issues

This page covers the most frequently encountered issues when integrating with Aimable. If your problem is not listed here, reach out through our support channels.

Connection Problems

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

• Verify that your network allows outbound HTTPS connections to api.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 api.aimable.ai is allowlisted

A quick connectivity test:

curl -I https://api.aimable.ai/health

You should receive a 200 OK response. If not, the issue is likely network-related.

Authentication Errors

The most common authentication error is a 401 Unauthorized response:

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

To resolve this:

1. Confirm your API key is correct and has not been rotated or revoked
2. Check that the Authorization header is formatted as Bearer YOUR_API_KEY
3. Ensure there are no extra spaces or characters in the header value
4. 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:

{
  "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