Reliable API Integrations: Plan for Failures and Retries

Brand article supplied by Saglotech. Originally published on 20 October 2026.

An enquiry reaches your inbox, but no customer appears in the CRM. An order is paid, but the warehouse system still shows nothing to dispatch. These failures are easy to miss because each individual system can look healthy while the connection between them is not.

Reliable API integration is not simply about making two applications exchange a successful test message. A useful business integration also needs a plan for failures, retries, duplicate records, monitoring and recovery. This guide explains the questions to include when briefing a South African web development team, without requiring you to write the integration yourself.

Describe the business event before the technology

Start with a sentence such as: “When a valid website enquiry is accepted, store it and make it available to the sales team.” That describes an outcome. “Connect the website to the CRM” leaves important decisions unanswered.

Define the required fields, the destination record and the moment the business considers the task complete. Does the CRM need a lead, a contact or both? Should a missing company name prevent submission? Does the website tell the customer the request was received before or after it has been safely stored?

For every important field, name the authoritative system. An address maintained by the customer should not be overwritten by an older export without an agreed rule. If both systems can edit the same field, document how conflicts will be detected and resolved.

Separate storing the request from delivering it elsewhere

A common design question is what should happen when the receiving system is unavailable. For a non-payment enquiry, it may be appropriate to store the request locally, show an accurate acknowledgement and queue the external sync. That is different from pretending the CRM has already accepted the record.

Ask the developer to describe the states staff will see: waiting to sync, synced and failed, for example. Each state needs a clear meaning. A record marked “sent” should not merely mean that the application attempted a network request.

Some workflows require a stronger immediate guarantee or must stop if the destination cannot accept the transaction. Discuss the consequence with the people who run the process. The right failure behaviour depends on whether the task is a sales enquiry, a stock reservation or a financial operation.

Make retries safe

A timeout does not always mean nothing happened. The receiving application might have saved a record before the sender lost the response. Retrying the request without a stable reference could create another record or repeat an action.

Ask how the integration identifies the same business operation across attempts. A developer may use an idempotency key, a unique external reference or another supported mechanism. The implementation must follow the receiving platform's actual contract; adding a field called “unique” does not establish duplicate protection.

Stripe's webhook documentation illustrates why integrations must account for retries, duplicate deliveries and event-ordering behaviour. Those are characteristics to check in each provider's documentation, not universal timings or guarantees to copy from one platform to another.

Put limits around automated retries. Repeatedly sending an invalid record will not repair a missing mandatory field. Staff need a way to distinguish a temporary service failure from a request that requires correction, with a safe route to retry after that correction.

Show failures where someone can act on them

A server log is useful for developers, but it may not help the person responsible for today's orders. Agree an operational view showing the affected record, current state, last attempt and a useful error summary. Keep credentials and unnecessarily detailed customer information out of that summary.

Assign ownership. Who checks failures, who can correct records and who can request technical help? Specify which incidents need immediate attention and which can wait for the next review. An alert that everyone receives but nobody owns is not a response process.

Use a reference that appears in both systems where possible. That makes it easier to trace an enquiry without exchanging full customer exports. Also decide how long operational history is retained and how support access is reviewed.

Test more than the successful example

Ask for an acceptance exercise with controlled test records. Include a valid request, a missing required field, an unavailable destination, a repeated request and a request that succeeds after a temporary failure. The team should explain the expected outcome before running each case.

Check the user-facing journey as well. If an enquiry cannot be safely stored, does the customer see an honest failure message and a practical next step? If it is stored but awaiting external sync, does the response avoid claiming that another system has already completed the task?

For integrations that receive events, test the provider's supported authenticity checks. Keep verification secrets server-side and avoid exposing them in browser JavaScript. Where a provider offers a sandbox, use it. Do not create live charges, dispatches or customer emails simply to test error handling.

Record the results in the project acceptance notes. A demonstration of a single happy path is not sufficient evidence that duplicate handling, recovery or permissions work.

Plan reconciliation, not just alerts

Even a monitored integration needs a way to compare important records between systems. For a hypothetical store, the team might review paid orders against fulfilment records and investigate unmatched references. The exact process depends on the business, but it should identify omissions rather than rely on a customer complaint.

Agree what happens when someone repairs a record manually. The automated process must not later undo that repair or create another copy. Document whether the corrected record is marked resolved, linked to an existing destination or replayed through the normal sync path.

Include this work in the support scope. Initial development, provider changes, failed-record reviews and ongoing monitoring are separate activities. A quote should explain which are included and how additional work is authorised.

Questions to ask before approving the integration

Will an email notification prove that the integration worked?

No. Email delivery and application storage are separate outcomes. Verify the intended record and sync status rather than treating an inbox message as proof that all systems were updated.

Can we just retry every failed request?

Not safely without understanding the operation and the provider's duplicate-handling rules. Some failures need corrected data or a reconciliation check before another attempt.

Does a standard connector remove these responsibilities?

No. A connector may provide useful features, but someone must still configure field mappings, permissions, monitoring and recovery. Check its supported behaviour against your actual workflow.

Brief the outcome you need to trust

Bring a sample workflow, field list and description of failure consequences to the planning discussion. Remove real customer details from examples unless their use is appropriate and necessary. Saglotech's web development service can help assess a portal or integration project. Read our custom development comparison for the wider platform decision, or schedule a consultation to define storage, sync and recovery acceptance criteria before implementation.

Original article: Reliable API Integrations: Plan for Failures and Retries — Saglotech