How we handle authentication, rate limits and failure
Integrations rarely fail because someone could not work out the endpoint. They fail in the space between the happy path and production: a token that expired at 3am, a rate limit hit during a bulk import, a webhook delivered twice, a request that timed out after the remote system had already committed the change.
Authentication is the first thing to get right and the most common thing to get wrong. OAuth 2.0 refresh tokens need rotating before they expire, not after a user reports missing data. API keys belong in a secret store, not in a repository or a config file emailed around. Where a provider supports scoped credentials we request the narrowest scope that does the job, so a leaked key cannot do more damage than the integration needed to do.
Rate limits are treated as a design constraint rather than an error condition. That means backoff with jitter rather than immediate retry, batching where the API supports it, and queuing work so a burst of activity does not turn into a wall of rejected requests. Bulk operations use bulk endpoints where they exist, because looping single requests is how a one-hour import becomes a three-day one.
- Idempotency keys so a retried or replayed request cannot create a duplicate record
- Exponential backoff with jitter, and a dead letter queue for anything that exhausts retries
- Explicit API version pinning, so a provider release cannot silently change behaviour
- Structured request and response logging, so failures are diagnosed from evidence
- Sandbox and staging environments used before anything touches live data
- Alerting on failure rate and on silence — an integration that stops running is the harder failure to spot
What happens when the API changes
This is the part almost nobody addresses, and it is usually the buyer's real fear. An integration is not a finished deliverable. It is a permanent dependency on a system someone else controls, and that system will change on their schedule, not yours.
Providers deprecate versions. Fields get renamed. Rate limits get tightened without much warning. Authentication methods get replaced — and occasionally a provider simply changes what a response contains, which is worse than an outage because nothing errors and the data is quietly wrong.
Integrations built to survive that look different from integrations built to pass a demo. Responses are validated against what the code expects rather than trusted. Version deprecation notices are tracked and migrated ahead of the cutoff. Monitoring watches volume as well as errors, so an integration that stops receiving records raises an alert rather than looking healthy because nothing failed.
When something does break, someone has to fix it. That is the argument for keeping an integration under ongoing maintenance rather than treating it as a project that finished. The alternative is discovering the problem in a month-end report.
