space.vars.ionos\_cloud\_ai\_model\_hub API, their causes, and their solutions.
## Error format
Every error response carries an HTTP status and a JSON body listing one or more messages. Each message has a machine-readable `errorCode` and a human-readable `message`:
```json
{
"httpStatus": 400,
"messages": [
{
"errorCode": "VALIDATION_ERROR",
"message": "field 'messages' must not be empty"
}
]
}
```
Branch on `errorCode` rather than on `message`. The message is written for people and may be reworded, while the code is part of the API contract. A request that fails validation in more than one way returns one entry per problem, so a client can report them together.
{% hint style="info" %}
**Note:** The `529` overload response is the only exception to this pattern; it follows the OpenAI error format described in [Capacity errors](#capacity-errors).
{% endhint %}
## API errors
This table lists all API error codes grouped by **Type**:
* Client errors caused by invalid requests
* Model errors caused by model serving issues
* Capacity errors caused by rate limiting
* Server errors caused by internal failures
| **Code** | **Type** | **Overview** |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` - `VALIDATION_ERROR` | Client | Cause: A field is missing, malformed, or outside its documented range, such as a temperature above 2 or a tool definition without a function.name.
Solution: The message names the field. Correct it and resend. Retrying unchanged always fails.
Cause: The request body is not valid JSON.
Solution: Check for a truncated body, a trailing comma, or unescaped characters in a string.
Cause: A multipart form, such as an image edit request, could not be parsed.
Solution: Check the form encoding and that every file part has a filename.
Cause: The token is missing, malformed, expired, or revoked.
Solution: Check the token value and its expiry. For information on how to verify and renew it, see Troubleshooting.
Cause: The model does not exist, or it exists but cannot serve this endpoint. For example, an embedding model asked for a chat completion.
Solution: Call /v1/models for the current list, and check the model card for the capabilities it advertises.
Cause: The request path is not an endpoint of this API.
Solution: Check the path against the API reference, including the /v1 prefix.
Cause: The endpoint exists but does not accept this HTTP method.
Solution: Check the method for the endpoint in the API reference.
Cause: The request exceeds a documented size or count limit, such as the number of documents in a rerank request or the size of an inline image.
Solution: Split the request, or pass large media as a remote URL rather than inline.
Cause: Your contract's rate limit is exhausted.
Solution: Retry using exponential backoff (this response does not include a Retry-After header). Monitor the X-RateLimit-Remaining-Requests on successful responses to avoid reaching the limit. For more information, see Rate Limits.
Cause: The connection closed before the response was ready because the request was canceled or the caller timed out. The client never receives this error itself; it exists in logs only and is recorded so a canceled request is not counted as a service failure.
Solution: No action is required. Tokens generated before the disconnect are billed, since the model produced them; canceling only limits further generation, not what was already produced.
Cause: The model rejected the request. The status and explanation come directly from the model.
Solution: Review the returned error message and adjust your request accordingly. Retrying the same request without changes will result in the same error.
Cause: The model understood the request but did not implement part of it. For example, a sampling parameter that the model does not support.
Solution: Remove the unsupported parameter, or use a model that offers it. Retrying does not help.
Cause: The model could not be reached, or it stopped before it completed answering.
Solution: Retry after a brief wait. If it persists, check the status page and contact IONOS CLOUD Support. A partial answer is never returned in place of a complete one, and an answer that was not completed is not billed.
Cause: Too many large requests are currently in flight. Requests above 4 MiB, or those using chunked transfer encoding, are limited to two concurrent requests.
Solution: Wait for the duration specified in the Retry-After header before retrying. To keep requests below the threshold, pass media via remote URLs rather than an inline base64 payload.
Cause: Your own requests are being throttled to protect overall service capacity.
Solution: Wait for the duration specified in the Retry-After header before retrying, then resume sending requests at a lower rate.
Cause: Capacity is currently exhausted across the entire service.
Solution: Wait for the duration specified in the Retry-After header before retrying.
Cause: The request failed due to an internal server error on the space.vars.ionos\_cloud infrastructure. The code identifies which operation failed and is not intended for branching.
Solution: The request may or may not have completed, so retries are only safe for idempotent operations. If the issue persists, report it using the instructions in Persistent Errors.
space.vars.ionos\_cloud support with:
* The model you were using.
* The HTTP status and the `errorCode` you received.
* The **response headers**, in particular `X-Request-Id` and `X-Gateway-Version` to locate the exact request.
* The timestamp and time zone of the request.
For details on how to capture the headers, see [Troubleshooting](/cloud/ai/ai-model-hub/troubleshooting.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ionos.com/cloud/ai/ai-model-hub/error-codes.md?ask=