Skip to main content

Modeling a 400 Bad Request Schema in OpenAPI

A 400 response needs a documented, reusable error schema so clients can handle failures predictably.

Updated 5 min readMarkdown

Quick answer: A 400 Bad Request tells the client the request is malformed or failed validation, and it should carry a structured error body rather than a bare status code or plain string. In OpenAPI you define one reusable error schema under components/schemas, reference it from every operation's 400 response, and keep the same shape so clients use a single error-handling path.

What a 400 actually means

A 400 covers problems the client fixes by changing the request: invalid JSON, a missing required field, a value that fails a constraint, or a parameter in the wrong format. It is not a catch-all. The codes around it carry distinct meaning, and mixing them forces clients to guess.

Status Meaning Typical case
400 Bad Request The request is malformed or invalid Bad JSON, missing body, failed validation
401 Unauthorized Authentication is missing or bad No token, expired token
403 Forbidden Authenticated but not permitted Caller lacks permission
404 Not Found No resource matches the path Unknown id or URL
409 Conflict Request clashes with server state Duplicate key, stale version
422 Unprocessable Entity Valid syntax, semantic rule fails Some teams use this for validation

The 400 versus 422 line is a convention, not something OpenAPI enforces. Pick one for validation and apply it consistently; switching across endpoints is worse than either choice.

Build a reusable error schema

Put the error model in components/schemas, the reusable-components approach in the OpenAPI guide hub, so every operation references the same definition. A practical shape has a machine-readable code, a human-readable message, and an optional list of field-level details.

components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: invalid_request
        message:
          type: string
          example: "Request body is not valid JSON."
        details:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
    FieldError:
      type: object
      required: [field, message]
      properties:
        field:
          type: string
          example: email
        message:
          type: string
          example: "Must be a valid email address."

Mark the fields every error includes as required, and leave optional detail arrays omitted rather than returning an empty list with a different meaning. A stable code matters more than a polished message, because clients branch on the code, not the message.

Reference it from an operation

The response entry pairs a description with the media type and shared schema. The description explains why the 400 happened; the schema tells the client what the body looks like.

responses:
  '400':
    description: The request was malformed or failed validation.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'

If the same error can come back from every operation, define it once and reuse the $ref rather than redefining it inline. Inline copies drift until two endpoints return errors that look similar but no longer match.

When to use RFC 7807 problem details

RFC 7807 defines a standard problem object with type, title, status, detail, and instance, served as application/problem+json. It works well when several teams need one error contract, because the field meanings are already defined.

components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri

It is a choice, not a requirement; a custom code and message model is fine for one API. The failure mode is mixing the two, so decide early which one the service returns and document the media type.

Common mistakes that make 400 responses unreliable

  • No schema at all. Declaring the code without a content object leaves clients guessing whether the body is JSON, a string, or an HTML page.
  • A different shape per endpoint. When every operation invents its own error fields, no shared client handling is possible.
  • Treating 400 as a bucket. Authentication, permission, and conflict failures have their own codes and should not be rewritten as 400.
  • Leaking internals. Stack traces, SQL fragments, and file paths in the message expose implementation details and help attackers.
  • Documentation drift. The schema promises a code field the real response does not include, the error clients notice first.

After importing the spec into Powerduck, send a request that triggers a 400, such as a body missing a required field, and assert on the response fields so the documented structure matches what the server returns.

Frequently asked questions

Should I return 400 or 422 for validation errors? Either is defensible. Use 400 when invalid input is a malformed request, 422 to separate syntax from semantic validation, and stay consistent.

How do I return more than one field error at once? Use a details array where each entry names the field and explains the problem, so clients render every error instead of fixing one field per round trip.

What media type should the error body use? Match the API's normal type, usually application/json, or application/problem+json for RFC 7807. Avoid an HTML page for a JSON API.

Do I need to document 400 on every operation? Document it wherever a request can fail validation or parsing. Read-only operations still need it if malformed query parameters can produce one.

The bottom line

Treat the 400 body as a contract, not an afterthought. One reusable schema, referenced everywhere and verified against real failing requests, gives clients a predictable way to handle errors; a bare code and inconsistent shapes push that work onto consumers and guarantee drift.

No comments yet. Be the first to comment.