response-success-status-removed
Response success status removed.
Breaking change (level: error)
It removes something the response used to include, so a client that reads it no longer receives it.
What this check detects
A documented success status code (a 2xx) is no longer part of the response contract. A client that branches on that specific status, for example treating 201 differently from 200, can break when it stops receiving it, or when the server returns a status the client was not written to handle.
If a status is genuinely no longer returned, coordinate the change with clients; removing it silently from the contract is breaking.
Example
The 202 Accepted outcome was removed. A client with a code path for the async-accepted case no longer has it documented, and may mishandle it if the server still returns it.
How to handle this change
When oasdiff flags response-success-status-removed, you have a few ways to respond:
- Find a backward-compatible alternative. Redesign the change so clients that followed the old contract keep working, and agree on the approach with whoever introduced it.
- Release it in a new API version. Keep the current contract and introduce the change in a new version, then deprecate the old one with a sunset date so clients have time to migrate.
- Accept it as a deliberate breaking change. Sometimes a breaking change is unavoidable, such as an urgent or security fix. Approve it knowingly, document it in your release notes, and tell affected clients. This should be the exception, not a routine way of working.
If oasdiff's verdict does not match your API's compatibility policy, you can also change how it treats response-success-status-removed with a severity-levels file:
Put one rule per line; the level can be err, warn, or info, or none to disable the check entirely:
# severity.txt
response-success-status-removed warnThen pass it to oasdiff:
oasdiff changelog base.yaml revision.yaml --severity-levels severity.txt