API integration mistakes: How to find them before acceptance
One successfully transferred order does not prove an integration is reliable. You need to see what happens when a response disappears, a message arrives twice or one system fails. This guide turns common API integration mistakes into practical acceptance tests: what to prepare, which result to expect and what evidence to request from your supplier.

Your ERP, warehouse and customer portal are connected. The demonstration works: an order arrives and its status turns green. In production, however, the warehouse accepts a request, its response is lost and the portal tries again. That is when you discover whether you accepted a working business process or merely a working connection.
Our introductory API integration guide covers connection options, data mapping and typical costs. This article focuses on acceptance. The following scenarios propose tests for an illustrative order handoff to a warehouse; they are not results from testing a particular client.
01Agree on what finished actually means
Distinguish receiving a request, storing it for processing and completing the business step. “Accepted” may mean only that the request is waiting in a queue. Users need to know whether the warehouse actually holds the order, whether information is missing or whether a person must intervene. A technical response does not replace that agreement.
Choose a unique order identifier and an expected destination record. Document permitted states, acceptable delay and the person responsible for resolving problems. Do not impose immediate completion on every operation: reserving the last item and exporting overnight analytics have different requirements. Run each test in an isolated environment or a safe mode that cannot trigger real dispatch.
02Mistake: demonstration data hides differences in meaning
Prepare a dataset containing ordinary cases and deliberate exceptions. This is about more than an empty mandatory field. One system might send quantities in packs while another expects individual items. A number can have a valid format and still cause an incorrect shipment. Acceptance therefore needs someone who understands the warehouse rules.
| Test input | Expected outcome | Evidence |
|---|---|---|
| One pack containing several items | Quantity follows the agreed unit. | Source and destination records plus the conversion rule. |
| An unknown product code | A traceable rejection or paused operation. | A specific reason and an assigned person to correct it. |
| A missing value and an explicit zero | Unknown and zero are treated differently. | Results for both variants. |
| An address change after handoff | The agreed correction, without a silent overwrite. | Change history and destination confirmation. |
Include text and time boundaries, multiple currencies if relevant, and an incomplete record. Our data migration guide provides further context for checking meaning, rather than merely whether data can be parsed.
03Mistake: a timeout creates a second order
Let the destination write the test request, then simulate losing its response. Perform a controlled retry and two concurrent attempts. The result should contain one business operation with a traceable connection to the original request. Simply switching off the destination before any write happens does not test this situation.
Stripe’s idempotent request documentation illustrates using a key for safe retries. The scope and lifetime of that protection depend on the provider and API version. You must verify the actual implementation used by your warehouse.
Also test a person manually retrying the request on the following day. Establish how long the mapping is retained and what happens after it expires. If the partner lacks equivalent protection, the design must handle result lookup and uncertain outcomes another way. Adding an arbitrary header will not create a guarantee the receiving API does not implement.
04Mistake: an older message overwrites a newer state
Send a test update and its earlier predecessor in reverse order. Deliver an identical message twice as well. A shipment marked as handed over must not revert to an earlier state merely because a delayed event arrived. Some backward changes may be legitimate corrections; event meaning and the authoritative source state determine the right behavior.
Stripe’s webhook documentation explicitly warns about duplicates and does not guarantee delivery order. Read the interface contract for your actual provider. Message arrival time alone does not establish the order of business changes. The test record should show the final state, processed identifiers and the reason an older message was ignored.

05Mistake: one successful step makes the whole process look complete
Simulate the warehouse accepting an order while the portal fails to store confirmation. Then test the reverse: the internal record changes but the partner rejects the request. Establish which step can be safely repeated and which has already caused an external effect. Acceptance evidence must capture both systems’ states.
Deleting a local row does not necessarily cancel a partner’s reservation. Some failures need a subsequent corrective operation or a person’s decision. Distinguish pending completion, requiring correction and completed. Ask the supplier to demonstrate recovery for one specific item, including a check that it did not damage other transfers.
06Mistake: recovery retries overload the partner
In testing, restrict destination API throughput and temporarily increase the backlog. Observe the oldest outstanding order, retry counts and how processing slows down. AWS explains why uncontrolled retries can worsen overload, and how timeouts, increasing retry intervals and randomized timing help.
Consider a simple model: 60 orders arrive per minute and the destination processes 40. The queue grows by 20 per minute, or 300 in 15 minutes. If, after a repair, both arrival and processing run at 60 per minute, those 300 orders will not drain while the inflow remains unchanged. You need spare processing capacity or reduced intake. This illustration excludes additional failures and retries; it is not a recommended limit.
Include a permanently invalid record: it must not block every other item indefinitely. Our guide to scaling a growing application discusses the capacity implications.
07Mistake: green monitoring misses a missing record
Deliberately omit one message from the test dataset. A transfer with no error messages is still incomplete. Compare expected orders with actual destination records, including identifiers and meaningful totals. Matching counts can conceal one missing record and one duplicate.
| State of the illustrative dataset | Count | What it means |
|---|---|---|
| Expected orders | 10 | The source identifiers are known. |
| Confirmed by the destination | 8 | These items have evidenced destination records. |
| Pending | 1 | Age and the next planned attempt are visible. |
| Blocked by invalid data | 1 | An owner and correction are recorded. |
After correction, check the complete dataset again. Request a record of resolved discrepancies, not merely a message saying that the integration job finished.
08Mistake: a valid account can access somebody else’s data
In an authorized test environment, use one branch’s account against another branch’s record. Verify that both reads and writes are rejected and that sensitive content is absent from errors and logs. OWASP API Security highlights authorization for the particular object, rather than relying only on an authenticated account.
Acceptance should include replacing and revoking a key, not just the first successful login. For API version changes, prepare examples containing an added field, unknown status and changed format. The system should recognize an unfamiliar situation safely rather than quietly count it as success. Our API security guide explains further access and data controls.
09Accept evidence, recovery and ownership together
For each scenario, retain its input, expectation, actual result, integration version and references to related records. When a test fails, record the impact, owner and condition for retesting. The technical team confirms execution; the process owner confirms that the outcome makes business sense. Logs should not become an uncontrolled archive of personal information.
Before launch, agree which defects block acceptance and which have an approved temporary workaround. Expand the pilot only after a demonstrated correction, with a way to pause further handoffs. Technical release strategies are covered by our blue-green and canary deployment guide.
Through our integrations and API service, Listify can help define the workflow, failure scenarios and acceptance conditions. Send the system names, an example operation and the most common problem. An initial conversation does not require access keys.
10Frequently asked questions about API integration acceptance
Do we need failure tests for an off-the-shelf connector?
Yes, for the business process that matters. A connector may call an API correctly without handling your units, exceptions and corrections. Verify its actual configuration and agree who coordinates problems between the two suppliers.
Is a sandbox sufficient for every test?
A sandbox is a safe starting point. It may not accurately reproduce production limits, delays or every state. Document those differences and plan limited launch verification that cannot create unintended real orders or payments.
Should every failed request be retried automatically?
No. Retrying may resolve a temporary outage, whereas an unknown product usually needs data correction. An uncertain write outcome requires duplicate protection. Set the rules for the particular operation and the provider’s documented behavior.
What does accepting a webhook mean?
It confirms the agreed level of delivery. If further work runs asynchronously, acceptance may not mean the business process is finished. Before acknowledging, the design must prevent message loss; subsequent processing needs a traceable state.
Who should sign off the tests?
The technical supplier provides execution evidence and results. An appointed business process owner confirms their meaning. Where several suppliers are involved, appoint a coordinator beforehand so a failed test does not disappear between support teams.