Early access: features, availability, and pricing may change as Kyara Intelligence evolves.

API reference

Errors

Every error the API returns, in the OpenAI error envelope, and which ones are worth retrying.

Errors use the OpenAI error envelope, so OpenAI SDKs raise them as their usual error types. message is meant for people; branch on the HTTP status and code.

{
  "error": {
    "message": "Unsupported text generation parameter: messages.0.tool_calls",
    "type": "invalid_request_error",
    "param": "messages.0.tool_calls",
    "code": null
  }
}

Error codes

StatustypecodeMeaning
400invalid_request_errorinvalid_jsonThe request body is not valid JSON.
400invalid_request_errornullThe request failed validation, or the Authorization header is malformed. message explains the problem and param names the field.
400invalid_request_errormodel_not_foundThe model ID is not in the catalog.
401authentication_errorinvalid_api_keyThe token is missing, revoked, regenerated, mistyped, or an expired OAuth access token.
403permission_errorno_active_planThe account has no active plan and no top-up credits.
403permission_errorinsufficient_balanceYour balance cannot cover the estimated cost of the request.
403invalid_request_errorcontent_policy_violationYour input was flagged by content moderation.
404invalid_request_errornullThe endpoint does not exist.
413invalid_request_errorrequest_too_largeThe request body is larger than 16 MB.
429rate_limit_errorrate_limit_exceededThe model is temporarily rate limited.
500server_errornullAn unexpected error.
503server_errorservice_unavailableGeneration, or the token check, is temporarily unavailable.

When the model itself rejects a request, for example a prompt longer than its context window, you get its status and message in the same envelope.

Validation errors

A 400 with a null code is a request the API refused to send to the model. param points at the problem:

  • An unsupported field inside a message, stream_options or reasoning is named in full, such as messages.0.tool_calls, and message reads Unsupported text generation parameter: ….
  • Any other problem with model or messages, such as a tool role or an image in content, sets param to model or messages.
  • Other parameters are named by their path, such as stop or reasoning.effort.

Unknown top-level parameters never cause this error: they are dropped. See Unsupported features.

Errors during a stream

Once a stream has started, the status is already 200. If generation then fails, the stream ends with an error event instead of data: [DONE]:

data: {"error":{"message":"Upstream stream failed","type":"server_error","param":null,"code":"upstream_stream_error"}}

Retrying

  • Retry 429, 500, 503 and upstream_stream_error with exponential backoff.
  • Don't retry other 4xx errors unchanged: fix the request, the key, or the balance first. After insufficient_balance, a lower max_completion_tokens may get the request through.
  • Failed requests are never billed, including streams that fail partway through, so retrying them costs nothing extra.