A payment provider adjusted a response field, a shipping API tightened validation, an authentication service changed an error format. Your application started failing and nothing in your repository changed. Vendors will keep doing this, sometimes with notice buried in a changelog nobody subscribes to. The realistic goal is not prevention but containment.
01Keep vendor shapes out of your domain
The most damaging pattern is letting a vendor's response structure flow through the entire application. When their JSON becomes your internal model, a change to one field propagates into every layer that touched it, and the blast radius of their decision is your whole codebase.
An adapter that translates vendor responses into your own types confines the change to one file. This is the single highest-value structural decision in any integration, and it costs very little when done at the outset.
| Measure | Effort | Protects against |
|---|---|---|
| Adapter layer for each vendor | Low | Shape and field changes |
| Validate responses on receipt | Low | Silent nulls and type changes |
| Timeouts and circuit breakers | Low | Slowness and outages |
| Contract tests against sandbox | Medium | Advance warning of changes |
| Fallback behaviour per feature | Medium | Total vendor unavailability |
02Validate what arrives rather than trusting it
Parsing a response into a typed structure with validation means a change surfaces immediately at the boundary, with a clear message about which field is wrong. Without it, a field that becomes null propagates as undefined into business logic and fails somewhere unrelated, often much later and in a way that obscures the cause.
Validation errors should be logged with the raw payload attached. When a vendor changes something, that log entry is the difference between a five minute diagnosis and an afternoon of speculation.
03Decide what happens when the vendor is unavailable
Every integration needs an explicit answer to the question of what the product does when this dependency fails. For an address lookup, allowing manual entry is fine. For payment authorisation, failing clearly is correct. Deciding in advance turns an incident into a degraded feature rather than an outage.
Timeouts must be short and explicit. A default client timeout measured in minutes means a slow vendor exhausts your connection pool, and their degradation becomes your total unavailability - a failure mode that is entirely within your control to prevent.
| Integration | When it fails | Rationale |
|---|---|---|
| Payment authorisation | Fail clearly, do not retry blindly | Correctness over availability |
| Address autocomplete | Fall back to manual entry | Convenience feature |
| Email or SMS sending | Queue and retry | Delay is acceptable |
| Analytics events | Drop or buffer locally | Must never block a user |
| Identity provider | Existing sessions continue | Avoid logging everyone out |
04Get warning before your users do
Contract tests running against the vendor's sandbox on a schedule detect shape changes before they reach production. This is one of the few genuinely proactive controls available, and it turns a customer-reported incident into a failing scheduled job.
Subscribe to status pages and changelogs, and record for each vendor who owns the relationship internally. Notice of breaking changes is frequently sent to a single email address configured years ago by someone who has since left.
05Log enough to prove where the fault lies
Record request and response metadata for external calls - endpoint, status, latency, correlation identifier, and payloads with secrets redacted. When a vendor asserts nothing changed, this is what settles the discussion, and it materially shortens support cycles.
It also lets you distinguish between their outage and your bug, which during an incident is the first thing you need to establish and the hardest thing to determine without instrumentation.
Topics
Aarav Patel
Principal Engineer · SyncTrix
Writes about the engineering decisions behind production systems - architecture, delivery and the trade-offs that only show up at scale.
Building something like this?
SyncTrix engineers AI, SaaS, platform and cloud systems for enterprises and high-growth teams. Tell us what you're shipping and we'll scope it with you.
Talk to an engineer