OpenAI API breaking changes, updated weekly

Every verified OpenAI API trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all OpenAI API traps.

1. fg-0567· added 2026-10-27· last checked 2026-10-27

   With no hard spend limit on your OpenAI organization or project, a traffic spike or leaked key is billed in full

   Symptom

   Spend alert emails arrive but API traffic keeps running

   Fix

   Set a monthly spend limit with Enforce a hard limit turned on, for the organization and for the project your app's key belongs to, and keep spend alerts below it as early warnings. When a limit is hit, requests fail with 429 and the code organization_spend_limit_exceeded or project_spend_limit_exceeded, so show users a clear message. Enforcement is not instant, so recorded spend can slightly pass the limit.

2. fg-0136· added 2026-10-15· last checked 2026-10-15· deadline 2026-08-26

   Assistants API calls stopped working after the 2026-08-26 shutdown

   Symptom

   Requests to /v1/assistants, /v1/threads and thread runs fail where they used to succeed

   Fix

   Move runs to responses.create and threads to conversations. Keep assistant settings such as model, tools and instructions in your own code rather than in reusable prompts (v1/prompts), because OpenAI set reusable prompts (v1/prompts) to shut down on 2026-11-30.

3. fg-0133· added 2026-10-15· last checked 2026-10-15

   429 from OpenAI is an empty credit balance, not a rate limit, so retries never succeed

   Symptom

   429 with error.type insufficient_quota

   Fix

   Check error.code before retrying. Retry only rate limit codes, and surface credit or quota errors immediately so someone adds credits.

4. fg-0135· added 2026-10-15· last checked 2026-10-15

   Agents SDK logs 'OPENAI_API_KEY is not set, skipping trace export' when using another model provider

   Symptom

   OPENAI_API_KEY is not set, skipping trace export

   Fix

   Disable tracing, or give the exporter its own OpenAI key.

5. fg-0137· added 2026-10-15· last checked 2026-10-15· deadline 2026-10-23

   Code calling gpt-3.5-turbo, gpt-4, gpt-4-turbo, o1, o3-mini or o4-mini breaks on 2026-10-23

   Symptom

   Model ids that coding assistants still suggest by default stop being served

   Fix

   Replace each model with its listed substitute: gpt-3.5-turbo and o4-mini move to gpt-5.6-terra; gpt-4, gpt-4-turbo, gpt-4o-2024-05-13, o1 and o3-mini move to gpt-5.6-sol; o1-pro moves to gpt-5.6-sol with reasoning.mode pro; gpt-4.1-nano moves to gpt-5.6-luna. Keep the model id in configuration so the next retirement is a one line change.

6. fg-0139· added 2026-10-15· last checked 2026-10-15

   OpenAI() raises "unexpected keyword argument 'proxies'" on a fresh install

   Symptom

   TypeError: Client.__init__() got an unexpected keyword argument 'proxies'

   Fix

   Upgrade openai to 1.55.3 or later, or pin httpx below 0.28.

7. fg-0140· added 2026-10-15· last checked 2026-10-15

   Realtime sessions opened with the OpenAI-Beta: realtime=v1 header stopped connecting in May 2026

   Symptom

   Voice agent built on the Realtime beta fails to open a session

   Fix

   Remove the beta header, move to a GA realtime model, and retest every client event your code sends and handles against the GA reference.

8. fg-0141· added 2026-10-15· last checked 2026-10-15

   Reasoning model returns empty text with status incomplete while you are still billed

   Symptom

   response.output_text is an empty string

   Fix

   Leave a large budget, OpenAI suggests at least 25000 tokens when starting out, and check status before reading the text.

9. fg-0144· added 2026-10-15· last checked 2026-10-15

   Uploaded PDF rejected: Expected a file with an application/pdf MIME type, but got unsupported MIME type 'None'

   Symptom

   Invalid file data: 'file_id'. Expected a file with an application/pdf MIME type, but got unsupported MIME type 'None'.

   Fix

   Upload with a filename and content type tuple and purpose user_data, then use the new file id.

10. fg-0143· added 2026-10-15· last checked 2026-10-15

    Strict structured output rejects the schema: 'required' must include every key in properties

    Symptom

    Invalid schema for response_format: In context=(), 'required' is required to be supplied and to be an array including every key in properties.

    Fix

    Make optional fields required but nullable, replace free form dicts with arrays of key and value objects, and wrap unions inside a root object.

11. fg-0132· added 2026-10-15· last checked 2026-10-15

    400 'Unsupported parameter: max_tokens is not supported with this model' on reasoning models

    Symptom

    Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.

    Fix

    Send max_completion_tokens on Chat Completions, or max_output_tokens on the Responses API.

12. fg-0142· added 2026-10-15· last checked 2026-10-15

    Streamed chat completions report no token usage, so cost tracking records zero

    Symptom

    chunk.usage is null on every streamed chunk

    Fix

    Set include_usage, read usage from the last chunk, and guard code that indexes choices[0].

13. fg-0134· added 2026-10-15· last checked 2026-10-15

    After upgrading openai-python to 3.x, import httpx fails, respx mocks stop working, or TLS verification breaks

    Symptom

    ModuleNotFoundError: No module named 'httpx'

    Fix

    Migrate custom clients and mocks to httpx2 equivalents, install system CA certificates or set SSL_CERT_FILE, and add httpx yourself only as a temporary bridge.

14. fg-0145· added 2026-10-15· last checked 2026-10-15

    zodTextFormat with Zod 4 fails: schema must be a JSON Schema of type object, got type string

    Symptom

    Invalid schema for response_format: schema must be a JSON Schema of 'type: "object"', got 'type: "string"'.

    Fix

    Upgrade openai to 6.7.0 or later, or pin zod to version 3.

15. fg-0138· added 2026-10-15· last checked 2026-10-15· deadline 2026-10-23

    Image generation with dall-e-3 or gpt-image-1 fails after their shutdown dates

    Symptom

    images.generate with model dall-e-2 or dall-e-3 fails since 2026-05-12

    Fix

    Switch to gpt-image-2.5-sunburst or gpt-image-2.5-flare, and keep the model id in configuration.