Paste an old and a new error response above and select Compare error responses to see the breaking-response drift and a release note.
About the API error contract diff
The API error contract diff turns two error response examples into a short breaking-change card so you can decide what to do before you release an SDK or API change. An error response can look similar by eye and still drop a field a client depends on, change the machine-readable error code consumers branch on, change a value type, or move to a different HTTP status. This tool surfaces those changes so a person can catch them before the change ships.
Paste the old error response and the new one, optionally set each side's HTTP status code, and select Compare error responses. The tool flattens each payload into a field map and reports a row per change: removed fields, added fields, value-type changes, error-code changes, and status changes. Each row carries a severity and a plain-language SDK impact, and you can download a findings CSV or copy a markdown release note. Everything runs in your browser. The payloads you paste, the field values, and any API names are never uploaded or stored.
How to use
- Collect the old error response body and the new one as JSON (for example from a captured response, a fixture, or your test suite).
- Paste the old response into the left box and the new response into the right box. A sample pair is loaded by default so you can see how it works.
- Optionally type each side's HTTP status code (for example 400 and 422) so a status change is included in the diff.
- Select Compare error responses to see the breaking-response drift.
- Review the table: each row shows the field, the change, the old and new type, a severity, and the SDK impact.
- Select Download findings CSV or Copy release note to keep a record before you release the change.
Worked examples
removed field flagged Breaking
A field present in the old response but gone from the new one is flagged as breaking, because a client that reads it will get nothing back.
error code change flagged Breaking
When the machine-readable error code value changes, clients that branch on the old code stop matching, so the change is flagged for a deprecation plan.
added field flagged Info
A new field in the response is additive: existing clients ignore it, so it is surfaced as info to document rather than as a breaking change.
Frequently asked questions
- What should I paste into each box?
- Paste a single JSON error response body in each box: the old shape on the left and the new shape on the right. You can use a captured response, a test fixture, or an example from your docs. The tool reads the fields, value types, and the error code from each and compares them.
- Why does the tool run on pasted payloads instead of calling my API?
- Keeping it paste-only means nothing about your API leaves your browser, the diff is deterministic, and the tool does not depend on network access or your auth. OpenAPI error-response import is a planned follow-up; the first version reads payloads you paste.
- How does it pick the error code field?
- It looks for a field whose name is a machine-readable error code (code, error_code, errcode, or status_code) and is present in both responses. When that field's value changes, the change is reported as a breaking error-code change. A generic discriminator like a problem+json type URI is not treated as an error code.
- How are arrays compared?
- First ship compares an array field by its first object item only, using a field[] path. That catches the common case where a list of error details changes shape. Comparing every item shape across a list is a planned follow-up.
- Is the payload uploaded anywhere?
- No. The parsing and the whole diff run in your browser. The payloads you paste, the field values, and any API names are never sent to a server or saved. Download the findings CSV or copy the release note before you close the tab.
- Does a clean result mean the change is safe?
- No. The diff is a deterministic comparison of the two examples you paste, not a guarantee about every consumer. A clean result means these two responses share the same fields, types, error code, and status; you should still review behavior changes and test real consumers before you release.
Use this again tomorrow
Save this page so it's one tap away when you need a quick result.
Ready for a quick Daily Challenge?
Play Daily Challenge on sts.games