OpenAI response_format JSON Schema Fix

response_format errors usually mean the request JSON parses, but the structured-output schema does not match the API shape.

Symptoms

  • The error mentions response_format or json_schema.
  • Plain text responses work but structured output fails.
  • A schema copied from application validation does not work in the API request.

Likely causes

  • The schema object is wrapped incorrectly.
  • Required fields or additionalProperties are inconsistent.
  • Unsupported JSON Schema features are included.

Fix steps

  1. Start with a small object schema and add fields gradually.
  2. Check that required fields match properties.
  3. Remove validation features the API does not support.
  4. Use the OpenAI API Request Checker for static shape warnings.

Verify the fix

  • Send a minimal structured-output request.
  • Validate the request body as JSON first.
  • Compare response_format shape against official API documentation.

FAQ

Is this a JSON syntax problem?

Not usually. The body can be valid JSON while response_format is semantically wrong.

Can I reuse any app schema?

Not always. Simplify it for API structured output and test incrementally.

Related tools and guides

OpenAI OpenAI API Request Checker

Statically inspect an OpenAI API request body for common JSON and parameter mistakes before sending it to the API.

 JSON JSON Validator and Formatter

Validate JSON, format it for reading, or minify it for compact API payloads without sending data to an external API.

 cURL cURL Command Builder

Build readable cURL commands for API requests with method, headers, JSON body and safe auth placeholders.

 OpenAI Debug OpenAI API Request JSON Before Sending

Most API request bugs are easier to fix before the request is sent. Start with valid JSON, then check model-family parameters and only then debug application code.

Last updated: May 18, 2026