# Identify the caller behind a compatibility incident

A server can be healthy while one supported client is broken. Trace the failing contract and client behaviour before treating the incident as a general outage.

By Cobnex editorial. Published 2026-09-10. Updated 2026-09-11.

## Capture the contract context

Find the request identifier, API version, operation and client or integration version. Record the response status and structured error without copying unnecessary sensitive payloads into the incident channel.

Determine whether the failure began with a server release, client update or data change. A newly returned enum value can expose a client assumption even when the API code did not change that day.

Compare one failing request with the prior documented behaviour. Look beyond field presence to defaults, ordering, pagination and error semantics.

## Reproduce with the affected client

Run the supported client version or its contract fixture against the candidate server. Inspect parsing and subsequent actions, not just whether the response matches the server schema.

Check whether the client retries, clears input or makes a wrong follow-up request. A compatibility defect can create load or duplicate actions as a secondary effect.

Use synthetic data that preserves the failing shape. If the issue depends on a specific field value, retain that structure without exposing the original business record unnecessarily.

## Contain the changed behaviour

Choose a compatible server adapter, targeted restoration or client fix according to the supported contract and deployment options. Avoid an unrecorded response hack that creates different behaviour for callers the team cannot later identify.

If the defect affects mutations, reconcile uncertain operations before encouraging users to retry. Preserve idempotency keys and target versions through recovery.

Communicate the affected operations and supported workaround in concrete terms. A broad "API issue" message is less useful than explaining which client versions and requests are affected.

## Verify and prevent recurrence

Test the repaired path with the affected client and a current client. Confirm both normal and error behaviour remain correct.

Add the missing contract fixture and record why the previous checks missed the change. It may have been a semantic assumption, incomplete caller inventory or a schema diff that did not cover runtime behaviour.

Close the incident with evidence that the supported caller can complete its business workflow again. Server uptime and successful generic probes are not sufficient when the failure lives in the interaction between two versions.

## Sources

- [Google AIP-180: backwards compatibility](https://google.aip.dev/180)
- [OWASP: logging guidance](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)