Description
The default entry in responses describes responses for status codes that are not defined individually. It is optional and is not reserved for errors, but it is useful when otherwise undocumented responses share a common format.
Potential impact
If the format of an actual error response is undocumented, clients or generated SDKs may handle it incorrectly.
Remediation
Document known successful and error responses. Add default when the remaining responses need a common contract, describing their meaning and any body actually returned.
Examples
This OpenAPI 3.0 excerpt adds default for errors without individual definitions alongside the bodyless 204 success response.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"responses": {
"204": {
"description": "Item updated successfully"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"patch": {
"operationId": "updateItem",
"responses": {
"204": {
"description": "Item updated successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}