Errors

Status codes, what each one means and what to do, and the shape of the error body.

Branch on the HTTP status code first. Every failure has one. Read the body for logging and for the message.

Status codes

Status	Meaning	What to do
`400`	A parameter is invalid, or the input cannot be processed. The causes are listed below.	Fix the request. A retry unchanged fails the same way.
`401`	No key was sent (`missing credential`), or the key is malformed or unknown (`invalid API key`).	Send `Authorization: Bearer <key>` with the key copied in full. Do not retry.
`403`	The key is revoked (`API key disabled`) or expired (`API key expired`), or the account cannot use the API (`account not found`, `API access disabled`).	Use another key, or contact support. Do not retry.
`404`	The model id, or an object id, does not exist or is not yours. An unknown model returns `the model "<name>" does not exist`.	Check the id against List models.
`413`	The request body is over 4 MB, or an upload is over 5 MB. An upload that is too large is not stored.	Send less, or split the document.
`429`	A rate limit was exceeded, or the account is out of credit.	For a rate limit, wait `Retry-After` seconds. For `insufficient_quota`, do not retry. See Rate limits.
`500`	A problem on Avey's side.	Retry with exponential backoff. If it persists, send the status code and body to support.
`502`	Avey could not get a valid answer from a service it depends on.	Retry with exponential backoff. If you were deleting a file, the retry runs the whole delete again.
`503`	Avey cannot serve the request now, for example because it is at capacity.	Retry with exponential backoff. This is not a problem with your key.
`504`	The request ran longer than Avey waits for an answer.	Stream long requests, and see Timeouts. Retry with a shorter request.

Causes of 400

A required field is missing, such as model and messages on chat completions.
A value is out of range, such as temperature above 2.
The prompt and the output limit together do not fit the 65,536-token context window. Files count as input.
reasoning_effort is not one of none, minimal, low, medium, high, or xhigh. The message starts Invalid value.
A Responses request uses background, context_management or reasoning.summary. The message is background, context_management and reasoning.summary are not available.
A Responses request uses a tool type other than function and file_search. The message is tool type "<type>" is not available.
An image or file is sent inline or as a URL. The message is send files and images as file_id: upload them with POST /v1/files first. See Files.
A file cannot be read. The message names the file and the reason, for example file <file_id> took too long to read; send a shorter file or this file's format cannot be read: <file_id>.
A file_id or vector store id is not yours or does not exist.
Your account was never set up on the API platform. The message is platform identity not initialized. Sign in to the API platform once.

Response bodies

Model and request errors use the OpenAI error body. The OpenAI SDKs parse it.

{
  "error": {
    "message": "the model \"example\" does not exist",
    "type": "invalid_request_error"
  }
}

Field	Meaning
`error.message`	Human-readable. Log it. Do not match on it.
`error.type`	`invalid_request_error` for a rejected request, `tokens` for a token-limit `429`, `insufficient_quota` when the account is out of credit, `server_error` for a failure on Avey's side.
`error.code`	Present on some errors only: `rate_limit_exceeded` on a token-limit `429`, the reason on an `insufficient_quota` `429`, `invalid_value` or `unsupported_parameter` on some `400`s.
`error.param`	The field at fault, when one can be identified.

A failure on Avey's side carries a generic message, such as the request failed; retry later. It never includes internal detail, so log the status code and the time and send both to support.

Key and account errors use a simpler body: { "message": "invalid API key" }. It has no error object, so code that reads error.message throws on it. Branch on the status code first.

A request-count 429 has no body.

An error before the first chunk is an ordinary HTTP error with the body above. An error after streaming started arrives as the last event: a data: frame on chat completions, or event: error on Responses. No data: [DONE] follows. Treat a chat stream that ends without [DONE] as failed. See Streaming.

Timeouts

Set your client timeout to 700 seconds. A long prompt with a long answer can run for minutes. A shorter timeout gives up on a request Avey is still answering.

Stream any request that can take more than a few minutes. While Olive works, a stream sends a heartbeat line about every second, so the connection is never idle. A non-streamed request sends nothing until the answer is complete, and a network path that closes idle connections can cut it.

A 504 means Avey stopped waiting. Retry with a shorter request, or stream the response to see progress. If a file is still being indexed after a 504, check it with List vector store files before you attach it again.

Retries

Retry a 429 with the loop in Rate limits. Retry a 500, 502 or 503 with exponential backoff and jitter. Retry a 504 as a stream or with a shorter request. Do not retry a 429 with insufficient_quota.

Do not retry a 400, 401, 403, 404, or 413 unchanged. Change the request or the key first.

If a failure matches nothing here, send the status code and response body to support@avey.ai.