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
codefield 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.
Comments
Join the discussionNo comments yet. Be the first to comment.

