API integration
Give Claude current docs so it doesn't invent fields, generate a typed client, and make every API failure visible.
-
How Do You Get Claude to Handle API Errors Properly? Have it build a table first: every failure the API documents, and what your code does about each one, whether that's retry, fail fast, tell the user or degrade. Level 3: WorkflowsA retry can help
- Connection errors and timeouts
- 408 and 5xx, including 529
- 429 with a retry-after header
A retry won't help- 400: bad request or your own spend limit
- 401, 403 and 404
- 429 with no retry-after: the spend cap
-
How Do You Generate a Typed API Client With Claude? If the API publishes an OpenAPI schema, generate the types with a tool, then have Claude write a thin client around them. Level 3: Workflows
- 1Schema or real response samplesthe source of truth
- 2Generated typesa tool, not the model
- 3Thin clientClaude writes this
- 4Validator at the boundarychecks what really arrives
-
How Do You Stop Claude Swallowing API Errors? Tell it, in the prompt and in CLAUDE.md, that no catch block may log and continue, that every request has a timeout, and that failures must surface as typed errors carrying the request ID. Level 2: ContextDo
- Raise a typed error
- Set a timeout on every request
- Log the request ID
- Requeue on a rate limit
Don't- Log and continue
- Return null on failure
- Check only the status on a stream
- Retry a write with no idempotency key
-
How Do You Stop Claude Inventing API Fields? Give it the current docs for the endpoints you need, and tell it not to use anything that isn't in them. Level 2: ContextFrom older codereturns a 400 today
- thinking type enabled
- A prefilled assistant message
- tool_choice any or tool
From the current docswhat the page says to use- thinking type adaptive, plus effort
- output_config.format
- tool_choice auto, with strict tools
Two different jobs
This lesson covers two situations that need different handling. If you're connecting your code to someone else's API, Claude works best from that API's current docs and schema, because its memory of a third-party API can be out of date. If you're calling Claude itself, start with Anthropic's official SDKs, which come in Python, TypeScript, C#, Go, Java, PHP and Ruby, with an ant command-line tool for scripts. They already give you types, streaming, error handling and retries, so you don't need a generated client. Install the Python one with pip install anthropic, or the TypeScript one from the @anthropic-ai/sdk package.
Work in this order
Most integration trouble comes from doing these steps out of order. Give Claude the real docs first, so nothing is written from memory. Next, list the failures and decide what happens for each, before any happy-path code exists. Then generate types from the schema and have Claude write a thin client around them, with a validator where responses arrive. Finally, sweep the result for places where an error can vanish without anyone hearing about it. The last step matters most for code that runs unattended, such as cron jobs and webhooks, where nobody is watching a console.
How do I get Claude to use an API correctly?
Give it the current docs for the endpoints you need, and tell it to use only what appears there and to say so if something is missing. In Claude Code, save the page to a file and reference it with @.
Why does Claude make up API endpoints?
Without the docs, it works from memory, which is a snapshot that may be out of date and may blend similar APIs. Giving it the current reference and forbidding anything not in it prevents most of this.
Does the Anthropic SDK retry failed requests?
Yes. Anthropic's docs say the Python SDK retries connection errors and 408, 409, 429 and 5xx responses twice by default, with exponential backoff. You can change this with the max_retries option, and setting it to 0 turns retries off.
What does a 529 error mean on the Claude API?
It's an overloaded_error, meaning the API is temporarily overloaded across all users. It can also arrive inside a stream after a 200 response. Retrying with backoff is reasonable, and the official SDKs do that for you by default.
Why do I keep getting a 429 from the Claude API?
If the response has no retry-after header and error.details.error_code is enforced_spend_limit_reached, your organization hit its tier's monthly spend cap. Retries keep failing until access resumes at 00:00 UTC on the first of next month, unless you move up a tier.