13 Common Pitfalls When Integrating Third‑Party APIs and How to Fix Them

Preface

In real projects we often need to call third‑party API interfaces to fetch or report data for exchange and communication.

This article discusses common issues when invoking third‑party APIs and how to solve them.

1. Domain Unreachable

Before integrating a new API, test the endpoint with a browser or Postman.

If the domain cannot be accessed in the development environment, you may need to ask operations to add your IP to the whitelist.

2. Signature Errors

Many APIs require a digital signature (sign) to prevent tampering, typically calculated as md5(concatenated parameters + secret).

Common causes of signature failures include incorrect parameter ordering, using production keys in a development environment, or applying the wrong number of MD5 iterations.

If the provider supplies an SDK for signature generation, use it; otherwise implement the algorithm according to the documentation.

3. Signature Expiration

Some APIs embed a timestamp in the signature, allowing requests only within a short window (e.g., 15 minutes) for security.

If a request fails after the window, simply generate a new request with an updated timestamp.

4. No Data Returned Suddenly

An API that previously returned data may stop doing so if the provider deletes the underlying data.

Before deploying to a test environment, confirm which data will be available and ensure it is not removed.

5. Token Invalidated

Some APIs require obtaining a token first and then passing it in the request header.

Cache the token (e.g., in Redis) but handle token expiration by catching related exceptions and refreshing the token immediately.

6. Interface Timeout

Timeouts are common when the external system’s call chain is complex.

Implement a retry mechanism, for example:

int retryCount = 0;
do {
    try {
        doPost();
        break;
    } catch (Exception e) {
        log.warn("Interface call failed");
        retryCount++;
    }
} while (retryCount <= 3);

7. HTTP 500 Errors

These may arise from missing required parameters, internal bugs, or unexpected code paths.

Retrying won’t help; you need to report the issue to the API provider.

8. HTTP 404 Errors

A 404 indicates the endpoint is unavailable—perhaps the provider renamed the API or the gateway configuration is outdated.

9. Incomplete Data (Missing Pages)

Some pagination APIs return an incorrect total page count, causing data loss.

Instead of relying on the reported total pages, continue fetching pages until a page returns fewer items than the requested page size.

10. Undocumented Parameter Changes

Providers may silently add new enum values (e.g., "off‑shelf") that your code treats as normal.

Coordinate with the provider to keep the enum definitions synchronized.

11. Intermittent Failures

Flaky responses (e.g., 503) often result from service restarts, node failures, or stale gateway configurations.

Report the issue promptly and add a retry strategy.

12. Documentation vs. Implementation Mismatch

Sometimes fields described in the API docs (e.g., a deletion flag) are not actually returned.

Two remedies: ask the provider to fix the implementation, or post‑process the response by comparing returned IDs with your database and deleting missing records.

13. Service Billing Issues

When a provider’s account runs out of credit, the API may return unexpected structures.

Log the raw response string before deserialization to aid troubleshooting.