Skip to content
Insights/Article

Before Integrating a Third-Party API, What Must Both Sides Confirm?

Key takeaway

Before integration, confirm in a signed handoff table: who generates business keys and how duplicates are recognized; which account authenticates and how credentials rotate; which errors are retryable; rate and timeout limits; the test environment; and how version changes are announced.

An API request card between two business systems showing business keys, credentials, error branches, and a signed handoff sheet

Take this illustrative scenario. At the project kickoff, the other side sends a 30-page API reference: which endpoints exist, which fields each request carries, what JSON comes back. Both teams assume work can start. Three weeks later, during integration, the order system resends a create request that had timed out, and the other system creates a second order. Later, a signature that passes in the test environment fails with production credentials.

An API reference describes how to call. It does not describe what both sides agreed the business means. After the document arrives, six things still need confirming.

What an API reference usually leaves out

A typical reference lists endpoints, methods, field names, sample payloads, and response codes. It usually does not say who generates the business key, whether a repeated request counts as the same event, who owns credentials, which errors may be retried automatically, what the rate limit is, whether the test environment matches production, or how much notice a version change gets.

These are not mere technical details. They decide whether the business creates duplicate records, loses orders, or leaves failures in a queue nobody owns. Write them into a handoff sheet both sides confirm before integration, not into a chat thread during the first failed test.

Business fields and keys: who generates them, and what a repeat means

Start with the business key for each object. Who generates the order number, customer ID, or material code; what format it uses; whether it may change; and which side wins a conflict. A key that is unique only inside each database is not enough. It has to match across both systems.

Then define how a duplicate request is recognized. A common pattern is an idempotency key: the caller sends a key, the receiver remembers it after the first success, and later requests with the same key return the first result instead of creating another record. Write down who generates the key, how long it is kept, and what a duplicate returns.

State the currency and smallest unit for money, so one side does not send yuan while the other expects cents. State the time zone and format for timestamps; an eight-hour offset is easy to miss. Do not pass internal status enums straight through. Make a status map: the other system's "confirmed" corresponds to which local state, and which state receives anything that does not map.

Authentication and permissions: whose account, and how credentials rotate

APIs normally use a dedicated system account, not an employee's personal login. A transfer or resignation should not break the integration, and a shared administrator account makes it impossible to tell which system called.

Confirm the credential type, who issues it, where it is stored, how often it rotates, and how it is revoked after a leak. Confirm what permissions the caller holds in the other system and whether read and write are limited to what is necessary. Confirm source restrictions such as an IP allowlist, and whether each call leaves an auditable log.

Do not put production credentials in frontend code, chat history, or a sample config file in the repository. Rotation needs an overlap: issue the new credential, confirm calls have switched, then disable the old one. Otherwise the rotation day takes the integration down.

Errors and retries: which requests may be sent again

Deciding whether to retry
  1. Network or temporary failure
  2. Retry with limits and idempotency
  3. Access, validation or conflict
  4. Correct the cause or review manually

Confirm idempotency and the server outcome before automatically retrying a create request.

Not every failure is retryable. Under RFC 9110 Section 9.2.2, GET, HEAD, OPTIONS, TRACE, PUT, and DELETE are idempotent: repeating an identical request has the same intended effect as sending it once. POST is not. Automatically retrying a POST that creates an order, without an idempotency key, can create two orders.

Divide retries into three groups:

  1. Safe to retry. A network timeout, a dropped connection, or a 503 from the other side. Retry with backoff, but cap the number of attempts and the total time. When a 503 carries Retry-After, wait as instructed instead of retrying immediately; see RFC 9110 Section 15.6.4.
  2. Do not retry automatically; reconcile first. A POST create request times out and you cannot tell whether the other side processed it. Query by business key first, confirm nothing was written, then resend.
  3. Retrying is pointless. Field validation, insufficient permission, expired credentials, a business rule rejection. Hand the original error or the agreed code to a person and the log; do not resend in a loop.

When the other side returns 409, RFC 9110 Section 15.5.10 defines it as a conflict with the current state of the target resource, and the response should include enough information for a person to recognize the source. That normally means a human look, not another automatic attempt.

Both sides maintain the error-code table together: what each code means, who handles it, whether it is retryable, and what wording the user sees. An English stack trace alone gives operations nothing to act on.

Rate limits, timeouts, and batches

Write rate limits as concrete numbers, and state whether they are per second, minute, or day, per account or per endpoint. Agree what the other side returns when the limit is exceeded, and how the caller queues or degrades.

For batch endpoints, define the maximum items per call, what a partial success returns, and how failed rows are retried. Do not assume a batch is all-or-nothing; many APIs process row by row.

Timeouts must match on both sides. If the caller times out at 10 seconds but the receiver finishes at 30, the caller believes it failed and retries, causing a duplicate. For asynchronous work, separate "accepted" from "completed": take a task ID, then poll or wait for a callback.

Test environment, versions, and cutover

The test environment should reproduce the main behavior of production, including authentication, error codes, and rate limiting. Test credentials stay separate from production credentials, and test data must not use real customer records. Agree on the integration window, who may create data in the test environment, and whom to call when it breaks.

Announce API changes in advance. Adding a field is usually compatible; removing a field, changing its meaning, changing an error code, or changing authentication can break the caller outright. Write down how the version is carried, how long the old version stays, and how both sides verify the switch.

Cutover needs a way back. Run a small share of traffic or a single account first, reconcile the results, then widen. Keep an on-call contact and a rollback switch on the day.

An API handoff table

Item

What to confirm

Provided by

How to verify

Business key

Generator, format, mutability, conflict rule

Both business owners

Cross-check one test order in both systems

Idempotency

Key, retention, duplicate response

Receiver

Send the same request twice; only one record appears

Field mapping

Status, money unit, time zone, enums

Both sides

Sign off a field mapping sheet line by line

Authentication

Account, rotation, scope, logs

Both technical owners

Call once with test and once with production credentials

Errors

Codes, retryability, owner, user wording

Receiver

Trigger one validation failure and one 503

Rate and timeout

Limits, batch size, partial success, timeout

Both sides

Load test or simulate a rate limit

Test environment

Address, data, window, contacts

Both sides

One complete task runs end to end in test

Version changes

Notice, lead time, old-version support

Both sides

Change log is available

The sheet does not need to be long, but every row needs a concrete answer and an owner. An empty row is where integration will stall.

Start with the smallest endpoint, such as reading one order status, and fill all eight rows before writing code. Once the read path works, move to create and update. How to write integration scope into a project is covered in business system development; how to organize existing spreadsheets and master data is covered in the system preparation guide.

How AI connects to ERP or OA, and the levels of permission that entails, is a separate discussion in connecting AI with ERP and OA. That article covers AI action levels; it does not replace this handoff table.

Sources

Let's talk about your project

Websites / Business systems / AI applications

Chat on WhatsApp