Error Codes

This guide lists the error codes returned by the 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:

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

Note: The 529 overload response is the only exception to this pattern; it follows the OpenAI error format described in Capacity errors.

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.
400 - INVALID_JSON	Client	Cause: The request body is not valid JSON. Solution: Check for a truncated body, a trailing comma, or unescaped characters in a string.
400 - INVALID_MULTIPART	Client	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.
401 - INVALID_TOKEN	Client	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.
404 - MODEL_NOT_SUPPORTED	Client	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.
404 - ROUTE_NOT_FOUND	Client	Cause: The request path is not an endpoint of this API. Solution: Check the path against the API reference, including the /v1 prefix.
405 - METHOD_NOT_ALLOWED	Client	Cause: The endpoint exists but does not accept this HTTP method. Solution: Check the method for the endpoint in the API reference.
413 - RESOURCE_LIMIT_ERROR	Client	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.
429 - RATE_LIMIT_EXCEEDED	Client	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.
4xx - UPSTREAM_REJECTED	Model	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.
422 - UPSTREAM_NOT_IMPLEMENTED	Model	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.
502 - UPSTREAM_UNAVAILABLE	Model	Cause: The model could not be reached, or it failed while producing a response. Solution: Retry after a brief wait. If it persists, check the status page and contact IONOS CLOUD Support.
503 - SERVICE_OVERLOADED	Capacity	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.
529 - user_overloaded	Capacity	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.
529 - server_overloaded	Capacity	Cause: Capacity is currently exhausted across the entire service. Solution: Wait for the duration specified in the Retry-After header before retrying.
500 - CHAT_COMPLETION_ERROR, COMPLETION_ERROR, EMBEDDING_ERROR, IMAGE_ERROR, RERANK_ERROR, RESPONSES_ERROR, CONVERSION_ERROR	Server	Cause: The request failed due to an internal server error on the 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.

Model errors

A model error means the model failed to generate a response and instead returned an error code, timed out, or returned a system message.

Capacity errors

A 503 or 529 error indicates temporary overload, not a client error or permanent outage. Clients that treat all non-200 responses as final abandon requests that succeed shortly after. Both status codes include a Retry-After header indicating when to retry.

The 529 response uses the OpenAI error format rather than the format shown above, so read error.code:

{
  "error": {
    "message": "The service is temporarily overloaded. Please try again shortly.",
    "type": "overloaded_error",
    "code": "server_overloaded"
  }
}

Always wait for the Retry-After interval rather than a fixed delay, so that clients do not retry in unison and prolong the overload. For the full retry guidance, see Rate Limits.

Note: Treat an error code you do not recognize as a generic failure of its HTTP status class. New codes may be added, and a client that rejects unknown codes breaks when one is.

Handling errors in Python

The API is OpenAI-compatible, so the openai library raises its usual exception types based on the HTTP status. This is the simplest way to handle errors if you already use that library.

Status	Exception
400, 413	BadRequestError
401	AuthenticationError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
5xx	InternalServerError
No response	APIConnectionError, APITimeoutError

import openai
from openai import OpenAI

client = OpenAI(
    api_key="[YOUR API TOKEN HERE]",
    base_url="https://openai.inference.de-txl.ionos.com/v1"
)

try:
    response = client.chat.completions.create(
        model="[MODEL NAME HERE]",
        messages=[{"role": "user", "content": "Hello world"}]
    )
except openai.RateLimitError as e:
    # 429 carries no Retry-After; back off exponentially.
    print(f"Rate limited (request {e.response.headers.get('X-Request-Id')})")
except openai.BadRequestError as e:
    print(f"Fix the request before resending: {e}")
except openai.APIStatusError as e:
    print(f"Request failed with status {e.status_code}: {e}")
else:
    print(response.choices[0].message.content)

To read the errorCode itself, take it from the response body:

except openai.APIStatusError as e:
    body = e.response.json()
    code = body["messages"][0]["errorCode"]

Persistent errors

If an error keeps occurring, contact 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.