Category: Status Codes & Responses
Description
Operations should define common HTTP error status codes appropriate for their method type and parameters.
What It Checks
This rule checks for commonly expected error responses:
- 400 Bad Request: For operations with request bodies
- 404 Not Found: For operations on specific resources (with path parameters)
- 409 Conflict: For POST, PUT, and PATCH operations
Why It Matters
Documenting common error responses:
- Complete Contracts: API consumers know what errors to expect
- Better Error Handling: Clients can handle specific error cases
- Documentation Quality: Comprehensive API documentation
- Developer Experience: Predictable error behavior
Examples
Good
paths:
/users/{id}:
put:
operationId: updateUser
parameters:
- name: id
in: path
required: true
requestBody:
content:
application/json:
schema:
type: object
responses:
'200':
description: User updated
'400':
description: Bad Request - Invalid input
'404':
description: Not Found - User doesn't exist
'409':
description: Conflict - Update conflict
Bad
paths:
/users/{id}:
put:
operationId: updateUser
parameters:
- name: id
in: path
required: true
requestBody:
content:
application/json:
schema:
type: object
responses:
'200':
description: User updated
# Missing 400, 404, 409 responses
Exceptions
- Operations where certain error codes don't apply
- Collection endpoints (404 may not apply for empty results)
- Operations that genuinely cannot produce certain errors
Configuration
This rule has no configuration options. It is either enabled or disabled.
Related Rules
- Rule 9: 401 Unauthorized - Authentication errors
- Rule 42: Consistent Errors - Error response consistency
- Rule 8: Response Error Codes - Error codes in response bodies