Category: Status Codes & Responses
Description
Operations that support content negotiation (multiple response media types) should define a 406 Not Acceptable response for when the client requests an unsupported format.
What It Checks
This rule checks operations where success responses (2XX) offer multiple content types and verifies they include a 406 response definition.
- Examines 2XX response content types
- Triggers when multiple content types are offered (e.g., JSON and XML)
- Checks for explicit 406 response definition
Why It Matters
When an API supports content negotiation, clients use the Accept header to request their preferred format. Documenting the 406 response:
- Sets Expectations: Clients know negotiation may fail
- Improves Debugging: Clear feedback when Accept header doesn't match
- Follows HTTP Standards: Proper use of HTTP content negotiation
- Complete Documentation: Accurately reflects API capabilities
Examples
Good
paths:
/users:
get:
operationId: getUsers
responses:
'200':
description: List of users
content:
application/json:
schema:
type: array
application/xml:
schema:
type: array
'406':
description: Not Acceptable - Requested format not supported
Bad
paths:
/users:
get:
operationId: getUsers
responses:
'200':
description: List of users
content:
application/json:
schema:
type: array
application/xml:
schema:
type: array
# Missing 406 response for content negotiation
Exceptions
- Operations that only support a single content type
- Operations without response content definitions
Configuration
This rule has no configuration options. It is either enabled or disabled.
Related Rules
- Rule 21: XML Alternative Representation - Multiple format support
- Rule 41: Consistent Media Types - Media type consistency