Skip to content
api

Integrate a third-party API with proper error handling and retries

Gets an AI to build a production-grade API client — authentication, retries, rate limiting, and typed responses — instead of a bare fetch call.

Who should use this

Is this prompt for you?

  • Developers integrating a payment, email, CRM, or data provider API
  • Teams that have been bitten by an integration that silently failed on rate limits or timeouts
  • Anyone who wants typed responses instead of loosely-typed JSON blobs
The prompt

Copy this prompt

Prompt
Build a client module for integrating with the [API name] API in my [language/framework, e.g. TypeScript/Node.js, Next.js server actions] project.

API details:
- Base URL / docs link: [paste or describe]
- Auth method: [API key header / OAuth2 / bearer token — describe]
- Endpoints I need to call: [list them, e.g. "POST /invoices, GET /invoices/:id, GET /invoices?status=paid"]
- Rate limits I know about: [describe, or say "unknown — handle defensively"]

Build:
1. A typed client with one function per endpoint, using TypeScript interfaces (or your language's type system) for both request and response shapes
2. Centralized auth handling (reading the key/token from environment variables, never hardcoded)
3. Retry logic with exponential backoff for transient failures (5xx, timeouts, network errors) — but NOT for 4xx client errors, which should fail immediately with a clear error
4. Rate-limit handling: respect any Retry-After header if the API sends one, otherwise use a sane backoff
5. Consistent error handling — throw or return a typed error object that distinguishes "network/API is down", "invalid input", and "auth failed" as different cases
6. A small in-memory or documented example of how to call this client from the rest of the app
7. Unit tests that mock the HTTP layer and cover: success, 4xx, 5xx-then-success-on-retry, and rate-limit response

Also tell me:
- What sensitive data (keys, tokens) needs to go in environment variables and never be committed
- Anything about this API's behavior that seems fragile or worth monitoring in production

Works well with Claude Code, Cursor and OpenAI Codex.

How to use it

Getting the best result

  1. 1Paste the actual API documentation or endpoint list — the AI cannot guess undocumented behavior
  2. 2Specify your real rate limits if you know them; otherwise let it build defensive defaults
  3. 3Review the retry logic carefully — retrying non-idempotent operations (like payments) needs extra care
  4. 4Store the generated environment variable names in your actual .env file and confirm nothing is hardcoded
Expected result

What you should get back

  • A typed API client module with one function per endpoint
  • Retry-with-backoff logic that distinguishes retryable from non-retryable errors
  • Rate-limit-aware request handling
  • Mocked unit tests covering success, client error, retried server error, and rate-limit scenarios
Tips

Get more out of this prompt

  • Explicitly flag non-idempotent endpoints (like "create payment") so the AI doesn't blindly retry them
  • Ask for a typed error union instead of throwing generic Error objects — it makes calling code much safer
  • If the API has webhooks too, handle those in a separate prompt — mixing inbound and outbound integration logic gets messy
Common mistakes

What to watch out for

  • Retrying non-idempotent requests (e.g. "charge card") and accidentally double-charging on a transient failure
  • Hardcoding API keys directly in the client instead of reading from environment variables
  • Not handling rate limits at all, causing the integration to fail under real traffic even though it worked in testing

Ready to put this prompt to work?

Pair it with an AI coding tool and a real project, then ship something this week.