api-integration-patterns

Wrap the API call in a withRetry helper that accepts maxRetries and an isRetryable predicate, retrying only transient errors like 500, 502, and 503 responses. Combine it with a circuit breaker so repeated failures short-circuit instead of hammering the external service.

Use idempotency keys derived deterministically from the operation identity, such as charge-{orderId}, and pass them to the provider's API. The same key across retries lets the provider deduplicate, so retries never create duplicate charges or emails.

Use the official SDK if it exists and is actively maintained, wrapping it in your own client class. Prefer raw HTTP when the SDK is unmaintained, has unpatched CVEs, or you need only one or two endpoints with precise control over headers and timeouts.

Compute an HMAC-SHA256 over the timestamp and raw request body, then compare it to the signature header using crypto.timingSafeEqual rather than ===. Also enforce a timestamp tolerance window, typically five minutes, to block replay attacks.

Respect the Retry-After header and wait before retrying, but cap the wait with a maximum budget so callers are not blocked indefinitely. Log rate limit events as warnings since they signal you may need to optimize call patterns or request a higher limit.