API contract evolution
Replay the error response an older client expects
Error contracts influence retries, forms and recovery. Test them with supported older clients, not only with a server-side schema validator.
In this article
Choose an error with client behaviour
Use a request rejected because an order version is stale. An older client may respond by reloading the order and asking the user to review the changed state.
Record the status code, structured error identifier and fields the client relies on. Keep the expected user action with the fixture. A test that only asserts a non-success response cannot show whether recovery still works.
Use the actual supported client or a faithful contract fixture where running it is impractical.
Change one part of the error
Run the candidate server and trigger the same stale-order condition. Inspect whether the client recognises it, preserves the user's draft and follows the intended recovery path.
A renamed error code or changed nesting can make the client show a generic failure or retry automatically. The latter is especially problematic if retries are inappropriate for the condition.
Test a validation error and an authority denial separately. Clients may have different handling for each, and collapsing them into one new error format can change both usability and security behaviour.
Exercise malformed and unfamiliar responses
Simulate a proxy error, missing optional detail and a new error subtype. The client should have a bounded fallback that does not crash or expose raw internal diagnostics.
Check retry limits. A client that treats every unknown response as transient can create repeated requests during a compatibility incident.
Preserve operation identifiers for commands whose result may be uncertain. Error-format changes should not cause the client to create a fresh business intention automatically.
Verify the complete recovery
For the stale-order case, let the client reload current state and submit a deliberately reviewed change. Confirm the correct target and version reach the server.
Inspect the user's visible message and retained input. A technically compatible error that clears a long form unexpectedly may still violate the product's expected behaviour.
Keep these cases with the supported client versions and run them before changing error serialization or middleware. Errors are part of the API contract because they tell callers what to do next, not merely that something went wrong.
Primary sources
Google AIP-180: backwards compatibilityAWS Builders' Library: idempotent APIsReferences checked 11 September 2026.