Error Response Schemas in OpenAPI
Design consistent error response schemas in OpenAPI. Define standard error objects with codes, messages, field-level validation errors, and reusable error components for clean API error handling.
Detailed Explanation
Error Response Schemas in OpenAPI
A well-designed API needs consistent error responses. Documenting error schemas in OpenAPI ensures that clients can handle errors programmatically and developers know exactly what to expect when something goes wrong.
Standard Error Object
components:
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
example: "RESOURCE_NOT_FOUND"
message:
type: string
description: Human-readable error message
example: "The requested user was not found"
details:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
description: Field-level validation errors
HTTP Status Code Mapping
paths:
/users:
post:
responses:
"201":
description: User created
"400":
description: Validation error
content:
application/json:
schema:
$ref: "#/components/schemas/ValidationError"
"401":
description: Authentication required
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"403":
description: Insufficient permissions
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"409":
description: Email already exists
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Validation Error Schema
ValidationError:
type: object
properties:
code:
type: string
example: "VALIDATION_ERROR"
message:
type: string
example: "Request body validation failed"
errors:
type: array
items:
type: object
properties:
field:
type: string
example: "email"
constraint:
type: string
example: "format"
message:
type: string
example: "Must be a valid email address"
Reusable Error Responses
Define common error responses once:
components:
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: RESOURCE_NOT_FOUND
message: The requested resource was not found
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
paths:
/users/{id}:
get:
responses:
"200":
description: Success
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
This pattern keeps your paths clean while maintaining consistent error documentation across all endpoints.
Use Case
Consistent error schemas are a hallmark of professional API design. Client developers use error response definitions to build robust error handling — parsing validation errors for form display, detecting auth failures for redirect logic, and logging structured error data. API gateways and middleware can validate that server error responses match the documented schema.