{
  "id": "llm/openai-structured-output-enum-violation",
  "signature": "openai.BadRequestError: Error code: 400 - {'error': {'message': \"Invalid 'response_format': 'type' must be one of ['text', 'json_object', 'json_schema'].\", 'type': 'invalid_request_error'}}",
  "signature_zh": "openai.BadRequestError: 错误代码：400 - {'error': {'message': \"无效的 'response_format'：'type' 必须是 ['text', 'json_object', 'json_schema'] 之一。\", 'type': 'invalid_request_error'}}",
  "regex": "openai\\.BadRequestError.*Invalid.*response_format.*type must be one of",
  "domain": "llm",
  "category": "config_error",
  "subcategory": null,
  "root_cause": "The response_format.type parameter is set to an invalid or unsupported value (e.g., 'json' instead of 'json_object' or 'json_schema'), or the model version does not support the specified format type.",
  "root_cause_type": "generic",
  "root_cause_zh": "response_format.type 参数设置为无效或不支持的值（例如，'json' 而不是 'json_object' 或 'json_schema'），或者模型版本不支持指定的格式类型。",
  "versions": [
    {
      "version": "openai==1.30.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "openai==1.35.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "gpt-4o-mini-2024-07-18",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The API strictly requires the 'type' key; an empty dict causes a different validation error: 'response_format must be a valid object with a type field'.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The API only accepts 'text', 'json_object', or 'json_schema' (for newer models). 'json' is not recognized and triggers the exact error.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Older versions don't support 'json_schema' at all, and may have different validation rules. This breaks other features and is not a sustainable fix.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Correct the response_format to use a valid type: `response_format={\"type\": \"json_object\"}` for unstructured JSON, or `response_format={\"type\": \"json_schema\", \"json_schema\": {\"name\": \"my_schema\", \"schema\": {...}}}` for structured JSON. Example: `client.chat.completions.create(model=\"gpt-4o-mini\", messages=[{\"role\": \"user\", \"content\": \"Hello\"}], response_format={\"type\": \"json_object\"})`.",
      "success_rate": 0.98,
      "how": "Correct the response_format to use a valid type: `response_format={\"type\": \"json_object\"}` for unstructured JSON, or `response_format={\"type\": \"json_schema\", \"json_schema\": {\"name\": \"my_schema\", \"schema\": {...}}}` for structured JSON. Example: `client.chat.completions.create(model=\"gpt-4o-mini\", messages=[{\"role\": \"user\", \"content\": \"Hello\"}], response_format={\"type\": \"json_object\"})`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using 'json_schema', ensure the model supports it (gpt-4o-mini and later, or gpt-4-turbo with specific versions). Check the model's capabilities via the API: `model = client.models.retrieve(\"gpt-4o-mini\"); print(model.supported_features)`.",
      "success_rate": 0.85,
      "how": "If using 'json_schema', ensure the model supports it (gpt-4o-mini and later, or gpt-4-turbo with specific versions). Check the model's capabilities via the API: `model = client.models.retrieve(\"gpt-4o-mini\"); print(model.supported_features)`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "For legacy models that don't support 'json_schema', fall back to 'json_object' and parse the output manually with a JSON schema validator like `jsonschema.validate()`.",
      "success_rate": 0.8,
      "how": "For legacy models that don't support 'json_schema', fall back to 'json_object' and parse the output manually with a JSON schema validator like `jsonschema.validate()`.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "将 response_format 更正为使用有效类型：`response_format={\"type\": \"json_object\"}` 用于非结构化 JSON，或 `response_format={\"type\": \"json_schema\", \"json_schema\": {\"name\": \"my_schema\", \"schema\": {...}}}` 用于结构化 JSON。示例：`client.chat.completions.create(model=\"gpt-4o-mini\", messages=[{\"role\": \"user\", \"content\": \"Hello\"}], response_format={\"type\": \"json_object\"})`。",
    "如果使用 'json_schema'，请确保模型支持它（gpt-4o-mini 及更高版本，或特定版本的 gpt-4-turbo）。通过 API 检查模型的能力：`model = client.models.retrieve(\"gpt-4o-mini\"); print(model.supported_features)`。",
    "对于不支持 'json_schema' 的旧模型，回退到 'json_object' 并使用 JSON 模式验证器（如 `jsonschema.validate()`）手动解析输出。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format",
  "official_doc_section": null,
  "error_code": "OAI-ERR-0400",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2024-08-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}