# Modeling a 400 Bad Request Schema in OpenAPI

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](https://www.powerduck.com/blog/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.

```yaml
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.

```yaml
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.

```yaml
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.
