# Why third-party APIs get a typed boundary

Canonical: https://stevenmoriasi.com/blog/enterprise-api-integration-framework
By [Steven Moriasi](https://www.linkedin.com/in/steven-moriasi/).
Source: https://github.com/steven-moriasi/enterprise-api-integration-framework
Date: 2025-08-18

## Context

Talking to someone else’s HTTP API is where timeouts, pagination quirks, leaked tokens, and retries that double-charge actually live. An LLM with tools inherits every one of those failures if the adapter is a raw `fetch`.

The [Enterprise API Integration Framework](https://github.com/steven-moriasi/enterprise-api-integration-framework) makes that path explicit.

## Decision

route → typed adapter → authentication → rate limit → circuit gate → bounded retry → HTTP → contract validation → safe result or structured error

API keys, bearer tokens, and OAuth 2.0 client credentials are strategies, not copy-paste. Timeouts are required. Structured errors omit provider bodies. Inbound webhooks are signed and checked for replay.

## What I rejected

A shared HTTP helper that retries every 5xx indefinitely, and forwarding the provider JSON to the caller “so the agent can decide.” Unbounded retry double-charges. Over-broad responses become prompt injection.

## Failure scenario

The billing adapter times out after the provider accepted the charge. The circuit is open for the budgeted window. The caller gets a typed error, not a raw body. A later retry uses the idempotency key the adapter required up front.

## Evidence

FastAPI/HTTPX adapters, contract tests, and documented timeout and circuit-breaker behaviour. Included GitHub, directory, notification, and billing shapes are mock contracts.

Inspect: [Repository](https://github.com/steven-moriasi/enterprise-api-integration-framework) · [Run locally](https://github.com/steven-moriasi/enterprise-api-integration-framework#readme)

_—by [Steven Moriasi](https://www.linkedin.com/in/steven-moriasi/)_