Errors with status code 4xx
This page describes all 4xx client error codes returned by the AIML API, along with real examples of error messages and guidance on how to diagnose and resolve each issue.
Error class overview
These are client-side errors returned by the AIML API when something is wrong with the request rather than with the server. The list below summarizes what each status code means.
400 Bad Request — The request contains invalid or missing parameters.
401 Unauthorized — The request is missing or uses an invalid API key.
403 Forbidden — The request is authenticated but not allowed (e.g., no credits).
404 Not Found — The requested endpoint or resource does not exist.
429 Too Many Requests — You sent too many requests and hit a rate limit.
Detailed examples of error messages and explanations are provided in the sections below.
The most frequently received messages
The most frequently received messages in this class are shown below. We will gradually expand this list.
400
"Body validation error!"
Your request body contains invalid or missing fields. Check the API schema for the selected model. The full error message usually includes hints like "Expected" and "Received" to show which parameter caused the issue.
400
"Unsupported value: 'messages[0].role' does not support 'system' with this model."
The provided role is not supported by the selected model. Check the API schema for the list of allowed values for messages[].role and update your request accordingly.
403
"You've run out of credits. Please top up your balance or update your payment method to continue: https://aimlapi.com/app/billing/"
Your credits or plan limits have been exhausted. Top up your balance or update your payment method on the Billing page to continue using the API.
401
"This request requires a valid API key. You can create a new API key on the Billing page: https://aimlapi.com/app/keys"
The request is not authenticated. The API key is missing, expired, or invalid. Pass a valid Authorization: Bearer <API_KEY> header from the Keys page in your dashboard.
404
-
The requested endpoint or resource does not exist. Check the base URL, path (for example /v1/chat/completions), and HTTP method used in your request.
429
"Too Many Requests"
You have hit a rate or concurrency limit by sending too many requests in a short period of time. Reduce the request rate, add retries with backoff, or queue requests before calling the API again.
Example #1: Body validation error
Below is an example of a 400 Bad Request with the generic "Body validation error" message. The API adds more details after this line (for example, Invalid enum value, Expected ..., Received ...). Use these hints to see which field was wrong and how to fix your request.
Last updated
Was this helpful?