Provider API Drift/Quota

1. Do not treat every provider failure as transient

When client code has not changed but an integration fails, separate at least three families: contract/version drift, quota or rate throttling, and transient service failure. A single retry strategy can hide real drift behind a retry storm and can misclassify throttling as a schema failure.

2. Record API version and contract expectation

For each request, record the API or model-endpoint version, operation, request shape, and expected response contract. “The same endpoint as before” is not enough evidence; a provider can deprecate a version, retire it, or change documented behavior with a migration path.

3. Separate contract observation from status code

A 200 transport success can still contain semantics that drift from the pinned contract. A 429 can preserve the contract perfectly while exposing quota pressure. Run the compatibility probe independently from the status/quota probe.

4. Classify breaking behavior from evidence

In this lesson, drift requires a mismatch between the pinned expectation and the observed contract: a required field is removed or renamed, a required type or meaning changes, a version is no longer supported, or a client-visible behavior breaks. An optional extra field or slower latency alone is not contract drift.

5. Treat 429 as throttling evidence, not schema evidence

In the deterministic fixture, 429 plus quota evidence and Retry-After or retry-after-ms is classified as throttling. The default containment is to reduce pressure and honor provider guidance; immediate unbounded retries can worsen the quota condition.

6. Keep 503 separate from quota exhaustion

A provider can return 503 for temporary overload while the contract and quota probes remain healthy. If retry guidance exists, bounded retry/backoff can be appropriate, but that evidence must not be relabeled as quota exhaustion or schema breakage.

7. Version pinning is containment, not a permanent guarantee

Pinning reduces silent contract movement and improves auditability, but the provider can still deprecate or retire that version. Keep lifecycle/deprecation evidence and the migration path separate, and preserve UNKNOWN when evidence is incomplete.

8. Make retry policy failure-class aware

CONTRACT_DRIFT and VERSION_RETIRED are not repaired by repeating the same request. QUOTA_THROTTLE should honor retry guidance, backoff, admission control, or queueing. TRANSIENT_SERVICE may use bounded retry. Every retry policy needs an attempt limit and a stop condition.

9. Use fallback only when it is bounded and qualified

A fallback provider or version must satisfy the required capability/contract and must not violate data, egress, or policy boundaries. If its qualification is not known, keep the fallback state as REQUIRES_REQUALIFICATION or UNKNOWN rather than declaring it safe.

10. Containment is not recovery

Reducing request rate or temporarily switching to a fallback can contain the incident, but closure requires more. Recovery needs an explicit rerun showing that compatibility, quota/service state, and request-level behavior are back inside declared bounds.

11. Provider Contract Drift & Quota Recovery Record v1

The owned artifact tracks thirteen dimensions: API version, contract expectation, contract observation, status code, quota usage, Retry-After, compatibility probe, failure class, retry policy, backoff state, fallback state, closure probe, and residual provider risk. Each dimension is labeled observation, authority, inference, or UNKNOWN.

12. Build classification from two independent probes

The contract probe asks whether the response remains compatible with the pinned contract. The quota/status probe asks whether rate/quota pressure or a transient service signal is present. The main lab outcomes are CONTRACT_DRIFT, VERSION_RETIRED, QUOTA_THROTTLE, TRANSIENT_SERVICE, HEALTHY, and UNKNOWN.

13. Re-test the classified cause for closure

For drift, the closure rerun must verify the corrected contract version or migration. For throttling, it must show quota-window recovery and bounded retry/admission behavior. For transient service failure, it must show service recovery without incorrectly attributing it to quota.

14. Lab: eight fixtures and 64 assertions

The lab is fully local and synthetic. The eight cases cover a healthy baseline, 429 with a healthy contract, 200 with contract drift, 503 with retry guidance, a retired version, conflicting or insufficient evidence, a transfer with a lower quota, and a transfer with 503 independent of quota. The evaluator emits eight fields per case for 64 assertions total.

15. Exit checklist and transfer

Before exit, explain which evidence belongs to contract/version and which belongs to quota/status, why the retry policy matches the failure class, what qualification the fallback has, and which independent probe establishes closure. In transfer, the schema stays compatible while quota drops and later a 503 with retry guidance appears; rebuild classification from new evidence instead of copying the earlier drift label.