API Error Codes

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.

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.
request_id	A unique identifier for the request.

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.

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.

Caution

Two responses do not use this envelope. See Responses that do not use the envelope before you write your error handling.

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.
404	Not found	The model does not exist, or it has been retired.	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.

Tip

If you are experiencing 500 or 503 errors, check the Infercom Status Page for any ongoing incidents or scheduled maintenance before contacting support.

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.
	unsupported_model	The model is not served by /v1/responses.	Use /v1/chat/completions, or pick a model the Responses API serves.
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 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.
404	model_not_found	The model ID does not exist, or the model has been retired. A retired model returns this code on /v1/chat/completions and /v1/responses. /v1/messages returns the same status with no code field.	Verify the model ID. For a retired model, see Deprecations for the replacement. Do not retry.
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

Two paths do not use this envelope. The body is still JSON, but error is a string instead of an object. Both omit request_id.

Handle both shapes before you read error.message.

Malformed image data

Returned by vision requests when the API cannot decode the image. HTTP 400.

{
  "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 requests when you force a specific function and the model produces no valid call. HTTP 400.

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

Defensive parsing

def read_error(response) -> tuple[str, str | None]:
    """Return (message, request_id) for every response shape."""
    try:
        body = response.json()
    except ValueError:
        # Not JSON, for example an error page from a proxy
        # between your client and the API.
        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")