Conversations API errors

The Conversations endpoints return errors in OpenAI’s nested error envelope — the same shape as the OpenAI Conversations and Responses APIs. This is intentionally different from the Agents API, which uses a flat { "error": string, "message": string } envelope.

Envelope

{
  "error": {
    "message": "Conversation not found.",
    "type": "not_found_error",
    "code": "not_found"
  }
}

Status / type / code reference

Status	type	code	Cause
400	invalid_request_error	invalid_cursor	?after= references an item that does not exist in this conversation.
401	—	—	Missing, malformed, or revoked API key. Emitted by the auth middleware before the route handler runs, so the body is the flat {"error": "Unauthorized", "message": "..."} shape — not the nested envelope shown above. Treat 401 as the one exception to the envelope rule on this surface.
403	permission_error	forbidden	The key authenticated, but the caller does not have access to this conversation.
404	not_found_error	not_found	conversation_id or item_id does not exist, or the conversation has been pruned by retention.

See also

• Quickstart — list + fetch flow.
• Request shape — query parameters and item types.
• Agents API errors — Kindo’s other agent surface, which uses a different (flat) envelope.