Aglet

Triage an API error contract drift

An error contract can drift while the HTTP request still reaches its endpoint. Start with one newly unknown failure and capture status, content type, safe code or type, and request correlation. Compare the client branch with a known validation or authorization response before changing retry behavior.

Establish what is happening

  1. Capture the response class

    Record method, endpoint, status, content type, response size, and correlation identifier. Keep only redacted error detail. Note whether the body was structured, empty, HTML, or malformed; a proxy response can resemble a remote contract change.

  2. Compare a known branch

    Replay a safe fixture that should produce a familiar validation or authorization error. Compare body fields, decoder result, retry choice, and visible recovery text. Check the client revision and intermediary path so a local decoder change is not attributed to the API.

  3. Bound retry consequences

    Count unknown errors by operation, environment, status, and branch. Separate permanent rejection, rate response, transient fault, and malformed body. Identify any writes that retried after an uncertain response, then preserve their operation identity for review.

What to carry forward

Triage ends when the unknown response, known comparison, selected client branch, affected operation cohort, and retry risk are recorded. Stop unsafe repeats. Route decoder, contract, and retry questions separately with the smallest remaining evidence request.

Technical background: RFC Editor reference.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow