> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infercom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes

> Infercom API error codes and HTTP status codes. Common error types, causes, and how to resolve them.

The Infercom API uses standard HTTP response status codes to indicate whether an API request was successful or failed.

When a request fails, the API responds with a JSON object containing details about the error.

## The error envelope

Every error response uses the same shape. The error detail is nested inside an `error` object, and the response carries a `request_id` alongside it.

```json title="Example error response"
{
  "error": {
    "message": "Invalid value for 'temperature': 99 is greater than the maximum of 2.",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_value"
  },
  "request_id": "dagkf1tcohtmhkppeq70"
}
```

| Field | Description |
| :---- | :---------- |
| `error.message` | A human-readable explanation of the problem. |
| `error.type` | The error class, for example `invalid_request_error` or `authentication_error`. |
| `error.param` | The request property that caused the error. `null` when no single property is at fault. |
| `error.code` | A stable machine-readable code. See [Error code reference](#error-code-reference). |
| `request_id` | A unique identifier for the request. |

<Aside type="tip">
  **Log `request_id` on every failed request.** It is the field our support team needs to trace a request end to end. Include it in every report you open at [support.infercom.ai](https://support.infercom.ai).
</Aside>

<Aside type="note">
  **`/v1/messages` uses the Anthropic error shape, not the envelope above.** The body carries a top-level `"type": "error"`, and `error` holds `message` and `type` only - there is no `param` or `code`. `request_id` is present on every status, though only some carry a `req_` prefix - the 401 does not. See [Anthropic SDK compatibility](/en/features/anthropic-compatibility).
</Aside>

<Aside type="caution">
  Three responses do not use this envelope, and one of them is not JSON at all. See [Responses that do not use the envelope](#responses-that-do-not-use-the-envelope) before you write your error handling.
</Aside>

## Error categories

Use the following table to understand the various error categories.

| HTTP status | Category             | Description                                                                    | Suggestion                                       |
| :---------- | :------------------- | :----------------------------------------------------------------------------- | :----------------------------------------------- |
| 400         | Bad request          | The server couldn't process the request due to invalid syntax or input values. | Review the API request syntax and parameters.    |
| 401         | Unauthorized         | Authentication credentials are missing or invalid.                             | Ensure valid API key/token is included.          |
| 408         | Request timeout      | The server terminated the request due to excessive processing time.            | Retry the request with optimized payload.        |
| 410         | Gone                 | The requested model is no longer available (deprecated or removed).            | Use a currently supported model.                 |
| 422         | Unprocessable entity | The request is well formed, but the model is not enabled on your plan.         | Use a model listed for your subscription.        |
| 429         | Too many requests    | Rate limit exceeded for your subscription tier.                                | Implement rate limiting or upgrade tier.         |
| 429         | Queue Full           | Too many requests are currently in flight; the server declined the request.    | Retry after a short delay or reduce concurrency. |
| 500         | Something went wrong | A server-side error occurred.                                                  | Retry later or contact support if persistent.    |
| 503         | Maintenance          | The model is temporarily unavailable due to maintenance.                       | Try again after some time.                       |

<Aside type="tip">
If you are experiencing 500 or 503 errors, check the [Infercom Status Page](https://status.infercom.ai) for any ongoing incidents or scheduled maintenance before contacting support.
</Aside>


## Error code reference

Use the following table to understand and troubleshoot errors programmatically.

| HTTP status | Error code                | Description                                                         | Suggestion                                                                                                                       |
| :---------- | :------------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------- |
| 400         | `context_length_exceeded` | Input/output tokens exceed model context limits.                    | Reduce prompt and response length to stay within model limits.                                                                   |
|             | `invalid_type`            | Parameter type mismatch (e.g., expected int but got float).         | Check the expected parameter types and correct the input.                                                                        |
|             | `decimal_above_max_value` | Decimal value exceeds the allowed maximum.                          | Adjust the value to fall within the allowed range.                                                                               |
|             | `decimal_below_min_value` | Decimal value is below the allowed minimum.                         | Increase the value to meet the minimum required threshold.                                                                       |
|             | `integer_above_max_value` | Integer value exceeds the allowed maximum.                          | Provide a smaller integer within the valid range.                                                                                |
|             | `invalid_value`           | Parameter value is outside the allowed range.                       | Check the accepted range for that parameter and resend.                                                                          |
|             | `unknown_parameter`       | The endpoint does not accept that parameter.                        | Remove the parameter. Check the endpoint's reference page for the parameters it accepts.                                         |
|             | `model_not_supported`     | The model exists but does not serve this endpoint.                  | Use a model listed for that endpoint. Check [Supported models](/en/models/infercomcloud-models).                                 |
|             | `unsupported_model`       | The model is not served by `/v1/responses`.                         | Use `/v1/chat/completions`, or pick a model the Responses API serves.                                                            |
|             | `model_not_found`         | Provided model ID does not exist.                                   | Verify the model ID and ensure it’s available in your subscription.                                                              |
| 401         | `invalid_authentication`  | Invalid or expired API key.                                         | Generate and use a valid API key from the Infercom Inference Service portal.                                                                |
|             | `invalid_api_key`         | The API key is incorrect or has been revoked.                       | Create a new key at [cloud.infercom.ai](https://cloud.infercom.ai) and update your client.                                       |
| 408         | `request_timeout`         | Request timed out due to server load or latency.                    | Retry with a smaller or optimized request payload. Additionally, consider upgrading to a higher subscription tier to avoid this. |
| 410         | `model_deprecated`        | The requested model has been deprecated and is no longer available. **No endpoint returns this code today.** `/v1/responses` returns `internal_error`, `/v1/messages` returns no `code` field, and `/v1/chat/completions` returns a plain-text body with no code at all. A fix is in progress with our platform provider. | Use a currently supported model listed in the documentation. Do not retry - a 410 is permanent. |
| 422         | `model_not_in_plan`       | The model exists but is not enabled on your plan. Returned by `/v1/chat/completions` and `/v1/messages`. The other endpoints return `400` for the same condition. | Use a model listed for your subscription, or contact support to add the model. |
| 429         | `insufficient_quota`      | Rate limit exceeded.                                                | Upgrade your plan for higher quota.                                                                                              |
| 429         | `queue_full`              | Too many in-flight requests; server declined the request.           | Retry after a delay or reduce request frequency.                                                                                 |
| 500         | `internal_server_error`   | An unexpected server-side error occurred.                           | Retry later. If the issue persists, contact support.                                                                             |
| 503         | `maintenance`             | Model is temporarily unavailable due to maintenance.                | Try again after some time or check maintenance announcements.                                                                    |


## Responses that do not use the envelope

Three paths do not use this envelope. On two of them the body is still JSON, but `error` is a string instead of an object. On the third the body is not JSON at all. All three omit `request_id`.

Handle all three shapes before you read `error.message`.

### Malformed image data

Returned by [vision](/en/features/vision) requests when the API cannot decode the image. HTTP 400.

```json
{
  "error": "Unable to decode image: cannot identify image file <_io.BytesIO object at 0x...>",
  "error_code": null,
  "error_param": null,
  "error_type": "invalid_request_error"
}
```

### A forced `tool_choice` that the model does not satisfy

Returned by [function calling](/en/features/function-calling) requests when you force a specific function and the model produces no valid call. HTTP 400.

```json
{
  "error": "Specified tool_choice with function name \"book_flight\", but the model output contains zero valid function call.",
  "error_code": null,
  "error_model_output": "I can help you book a flight from Munich to Lisbon...",
  "error_type": "Invalid function calling output."
}
```

This body adds a field the envelope does not define, `error_model_output`. It carries the text the model produced instead of the tool call. Note also that `error_type` holds a sentence here, not a code such as `invalid_request_error`.

### A retired model on `/v1/chat/completions`

Returned when the requested model has been deprecated and removed. HTTP 410.

This response is **not JSON**. It is served as `content-type: text/plain; charset=utf-8` with a plain sentence as the whole body:

```
The requested model (MiniMax-M2.5) is not available on SambaNova Cloud. For more information, please visit https://docs.sambanova.ai/cloud/docs/resources/deprecations. For further inquiries, please contact our support team at help@sambanova.ai.
```

Parsing this body as JSON raises a decode error. Check the response `content-type`, or catch the decode failure, before you read the body.

<Aside type="note">
  Official SDKs already survive this. The OpenAI Python SDK raises `openai.APIStatusError` with `status_code` 410 and the sentence in `.body`. The failure hits clients that call `.json()` on the raw response themselves - `requests`, for example, raises `requests.exceptions.JSONDecodeError`.
</Aside>

The same condition on `/v1/responses` and `/v1/messages` does return JSON.

<Aside type="caution">
  Do not retry a 410. The condition is permanent. Change the model ID instead. See [Deprecations](/en/models/deprecations) for current replacements.
</Aside>

### Defensive parsing

```python
def read_error(response) -> tuple[str, str | None]:
    """Return (message, request_id) for all three response shapes."""
    try:
        body = response.json()
    except ValueError:
        # Not JSON. Some errors, such as a retired model on
        # /v1/chat/completions, return a plain-text body.
        return response.text.strip(), None

    err = body.get("error")
    if isinstance(err, str):
        return err, None
    return err.get("message", "unknown error"), body.get("request_id")
```