External API Connector Guide

Wiring an agent up to a third-party API has predictable failure modes that are easy to skip under time pressure. This skill is a checklist to run before writing the integration code.

Before writing any request code

1. Check for an existing, official SDK/client library first — hand- rolled HTTP calls against a REST API tend to drift from the real contract (pagination, rate limits, error shapes) that a maintained SDK already handles correctly.
2. Scope credentials to the minimum permission the task needs. A read-only task should never hold a write-capable token; a single-channel Slack integration shouldn't request workspace-wide access.
3. Never hardcode credentials or embed them in generated code — read from environment variables or a secrets manager, and confirm the .gitignore actually excludes wherever they might land locally.

Handling the request lifecycle

• Rate limits are not exceptional cases — assume they'll be hit and handle 429s with backoff, not just a try/catch that surfaces an error to the user.
• Distinguish retryable failures (timeouts, 5xx, rate limits) from permanent ones (4xx auth/validation errors) — retrying a permanent failure just wastes calls and can trigger stricter rate limiting.
• Treat every external response as untrusted input — validate shape before using it, don't assume a documented schema is what actually comes back.

OAuth-specific

• Store refresh tokens securely, never in plaintext logs.
• Handle token expiry proactively (refresh before a call fails) rather than reactively (catch the 401, then refresh, then retry) when the SDK supports it — the reactive path still works but costs an extra round trip on every expiry.

When integrating multiple services

Keep each connector's auth/error-handling logic isolated per service rather than one shared abstraction that has to accommodate every provider's quirks — a shared interface for "call the external thing" is fine; a shared implementation of auth/retry logic across genuinely different APIs usually isn't.