An API integration is reliable only when the team can explain what happens to a business event after a timeout, duplicate request or external system change. That requires a contract that defines behaviour, idempotency for state changes, bounded retry, a visible recovery queue and API versioning with a migration plan. HTTP 200 alone does not prove that an order, document or other business outcome has actually been completed.
An API that returns the first response correctly is not yet a reliable integration. The real test comes when a message arrives twice, an external system changes a field, a call takes too long, or a response confirms acceptance of a request that is not processed later.
Stability is built into the contract and error behaviour, not into the ideal example in the documentation. This matters especially when an ERP exchanges orders, inventory, invoices or statuses with other systems. Technical ambiguity quickly becomes a business problem: a duplicate document, an unknown order status or a manual check with no clear trace.
A schema defines which fields exist. An integration contract must explain what they mean, when they are required, who may change them and what the receiving system does after receiving a message.
For each endpoint, document:
Documentation should also include negative examples. A developer often benefits more from seeing a rejected request caused by invalid data, insufficient permissions or a state conflict than from another perfect response. The business owner can then confirm whether the feedback matches the real decision a user needs to make.
A sound contract also distinguishes a synchronous confirmation of receipt from confirmation of the business outcome. If an API says that a request was accepted for processing, the client must know where and when to verify whether the final document or status was created.
When a client receives no response, it does not know whether the request failed or processing finished without confirmation. Repeating the call is the natural response. Without idempotency rules, that retry can create duplicate orders, documents or charges.
For operations that change state, use a stable request identifier tied to the same business intent. The destination must be able to recognise that the same request has already been processed and, on a safe repeat, return the same result or a clear indication of prior processing.
Consider an order sent from an online store to an ERP. If the store sends the same order again after a timeout, the ERP must not open a new order just because another HTTP call arrived. The request identifier must remain the same across attempts, and the processing record must remain available long enough to cover the expected retry pattern.
Not every action is equally suitable for automatic repetition. Where idempotency cannot be implemented, the documentation must clearly state the limitation, the method for checking the prior state and the responsible role that makes the decision before resending.
Automatic retry helps with short interruptions, but without limits it can amplify the problem. A large number of clients immediately repeating a request adds load to a system that is already recovering.
A retry policy should define:
An error caused by invalid data should not be retried automatically. It requires a data correction or a business decision. The same applies to insufficient permissions and requests that violate a published process rule.
An unprocessed message must end in a visible recovery queue, with its reason, business context and an option for controlled repetition. A queue is not a place where a message disappears. It is a work list for a person or team that can determine whether data should be corrected, the event resent or further processing stopped.
Changing a field name or the meaning of a status can be small in one system and expensive across ten integrations. Compatible changes should be added without breaking existing clients. Breaking changes require a new version, a published description of the behaviour difference and a clear migration period.
API management is not only about publishing endpoints. It includes records of who uses which version, deprecation rules, change communication and monitoring of actual traffic. Without those records, an old version cannot be retired safely and a new one is developed under pressure from unknown dependencies.
Before making a breaking change, the team should answer several questions:
HTTP 200 says that a call was accepted, not necessarily that the business process is complete. To track the full flow, use a correlation identifier through the source system, message queue, service and destination document. This connects one request to a specific order or invoice without relying on call time and guesswork.
An operational view should show the number of failed processes, the age of the oldest message, the duration of the full flow and items awaiting manual recovery. A technical metric without a business item makes it harder to speak with a user who wants to know whether an order was processed, rather than whether a service responded.
Before production, deliberately trigger a slow response, timeout, temporary unavailability, invalid token, changed schema and duplicate request. The goal is not to prove that an API can fail. The goal is to verify whether the rest of the process fails in a controlled way and leaves enough information for recovery.
Consumer-driven contract tests can detect a provider behaviour change that breaks a client early. A sandbox helps the integrator, but it must represent production error codes, limits and data rules closely enough. A sandbox that accepts every request does not prepare the team for the real decision required when an error occurs.
For critical connections, prepare an operational runbook. It should state where message status is visible, how uncontrolled retry is stopped, who may resend a message and how the final business outcome is confirmed. Have a person who did not write the integration test the runbook. If only the author can follow it, the knowledge is not yet part of the system.
When several business modules exchange data, the integration contract should be linked to process ownership rather than remain only a technical document. The overview of Business modules connected to ERP can help in that discussion, especially when the team needs to define where the source event is created and who confirms the final outcome.
API integration becomes reliable when success, delay and error are designed equally well. As a next step, select one critical flow, such as an order through to an ERP document, and walk through it with the team from timeout to manual recovery. If you cannot show the request identifier, contract version, queue state and confirmed business outcome, complete those parts before the connection becomes critical to daily operations.