API reference: errors and limits

Every error on /v1/* uses the OpenAI error format, so the OpenAI libraries raise their usual exceptions (BadRequestError, AuthenticationError, RateLimitError and so on).

{
  "error": {
    "message": "The Instant tier does not support function calling. Use Fast or Smart or Genius for active tool requests.",
    "type": "invalid_request_error",
    "code": "unsupported_tools",
    "param": "tools",
    "request_id": "b63d6449901d41e0b02e7f1a4af3b885"
  }
}

param names the field at fault. Quote request_id, also sent as the X-Request-ID header, when you ask your administrator about a request.

Status codes

Status	Meaning	What to do
400	The request has a field the server can’t use	Fix the field in param; retrying unchanged fails again
401	Missing or wrong API key (invalid_api_key)	Send Authorization: Bearer with a valid key
415	The body is not sent as Content-Type: application/json	Send JSON with that header
404	Unknown tier (model_not_found), or the endpoint is turned off (api_disabled)	Use a tier from /v1/models, or ask your administrator
429	A request limit was reached (rate_limit_exceeded)	Wait Retry-After seconds and send it again
502	The model’s answer did not pass a check	Retry; the server has already tried again once
503, 504	The model is busy or took too long	Retry with back-off

Error codes

Code	Status	When
invalid_api_key	401	The key is missing, wrong or revoked
model_not_found	404	model is not a tier your key may use
api_disabled	404	Your administrator has turned the endpoint off
unsupported_parameter	400	A field value the server does not take, named in param (see request fields)
invalid_request_error	400	An unknown field or a value of the wrong type, named in param
unsupported_tools	400	Tools were sent to a tier without capabilities.tools
unsupported_tool	400	A tool type other than function
unsupported_content_part, unsupported_input_item	400	An input part or item type the server does not take
unsupported_schema	400	A JSON schema feature that can’t be checked
invalid_tool_schema	400	A function’s parameters schema is not valid
invalid_response_format, response_schema_too_large	400	text.format or response_format is not valid, or its schema is over 64,000 characters
max_output_tokens_exceeded	400	max_output_tokens is over the tier’s limit for a request with tools
unsupported_vision	400	Images were sent to a tier whose capabilities.vision is false
context_length_exceeded	400	The request and the answer it needs don’t fit the tier’s context window. Shorten the input or use a tier with a bigger window
too_many_images, images_too_large	400	Over 8 images, 10 MiB for one image or 20 MiB in total
invalid_image, invalid_image_detail, unsupported_image_detail	400	The image can’t be read, or detail is not auto
unpaired_tool_output_image	400	A function output with images is not right after its function_call
reserved_image_marker	400	[img] or [img- in a tool definition, schema or call in a request with images
image_url_not_supported	400	An https image address, on a server that takes only data: URLs
image_url_not_allowed, image_url_not_public, image_fetch_timeout, image_fetch_failed, image_too_large, unsupported_image_mime	400	An image address your administrator allows could not be fetched or used
rate_limit_exceeded	429	Too many requests or open streams. Wait for Retry-After
image_fetch_busy	429	Image downloads are busy. Wait for Retry-After
invalid_structured_output, tool_choice_violation, empty_model_response	502	The model’s answer failed the schema or tool check after a retry. Send the request again
invalid_tool_call, incomplete_tool_call, incomplete_structured_output, incomplete_model_stream, server_error	502	The model’s answer was cut off or could not be read. Send the request again
model_unavailable	503	The model is not reachable right now
model_timeout	504	The model took too long

Request limits

Limit	Default
Requests per API key	60 a minute, across /v1/chat/completions and /v1/responses. /v1/models counts only toward the address limit
Open streams	4 at a time per API key, 8 at a time on the server. A refused stream gets 429 with Retry-After: 5
Requests from one network address	120 a minute, 40 in any 10 seconds, 16 at the same time
Wrong or missing keys from one address	20 in 10 minutes. After that the address gets 429 instead of 401 until the window passes
Images per request	8, up to 10 MiB each and 20 MiB in total
Input items per request (/v1/responses)	400 items, 100 messages

Your administrator can change these. A refused request does not count against any limit. When more than one limit applies, Retry-After gives the longest wait.

Request fields

/v1/responses refuses these values with HTTP 400. The endpoint keeps nothing on the server, so send the whole conversation in input each turn.

Field or value	Code
store: true, previous_response_id, conversation, background: true, prompt, truncation: "auto", a non-empty include, reasoning options, other service_tier values, context_management	unsupported_parameter
top_logprobs other than 0, text.verbosity other than "medium", stream_options with anything but include_obfuscation	invalid_request_error
Tool types other than function	unsupported_tool
input_file, input_audio and file_id parts	unsupported_content_part
Other input item types	unsupported_input_item
Any field not in the request body	invalid_request_error

/v1/chat/completions refuses n other than 1, functions, function_call and logprobs, with param naming the field. For web search use POST /websearch, and for PDF files use POST /pdf.

Common questions

What does HTTP 429 mean on ZenithAI's API?

A request limit was reached, for your key or for your network address. The body has the code rate_limit_exceeded and the Retry-After header says how many seconds to wait. The OpenAI libraries wait and retry for you.

Which ZenithAI errors are safe to retry?

429 after Retry-After, and the 502, 503 and 504 errors listed on this page. A 400 will fail again until you change the request, so fix the field named in param first.