Errors

Errors use the OpenAI error envelope, so OpenAI SDKs raise their normal typed exceptions.

Error shape

json

{
  "error": {
    "message": "Thread does not exist.",
    "type": "invalid_request_error",
    "param": null,
    "code": "thread_not_found"
  }
}

HTTP	type / code	When
400	invalid_request_error	Malformed JSON, missing messages/variables, bad UUID, malformed attachment, invalid timezone, malformed base64 image, or an ended thread.
401	unauthorized	Missing or invalid API key.
404	model_not_found	The API key's app does not support this endpoint (e.g. calling /runs with an AI Chatbot app key).
404	thread_not_found	The thread_id does not exist (or belongs to another user).
404	message_not_found	The message_id passed to /messages/{id}/suggestions does not exist.
403	suggestions_disabled	Follow-up suggestions are switched off for this agent.
429	rate_limit_exceeded	Too many concurrent requests for the app.
429	insufficient_quota	The model provider's quota is exhausted.
500	provider_not_initialized	No model provider credentials are configured for the app.
500	server_error	Model invocation failed or an unexpected internal error occurred.

Once a stream has started the HTTP status is already 200, so a failure arrives as a final error event followed by data: [DONE]:

text

data: {"error":{"message":"Generation failed.","type":"server_error","param":null,"code":null}}

data: [DONE]

ℹ Handle both places

Check for an error key on stream events as well as non-2xx responses — a request can validate fine and still fail during generation.