Claude API Fundamentals Best Practices

Twenty-five practices for reliable authentication, requests, and error handling when building on the Claude API with the official Python SDK.

Organized from setup and authentication through request design, error handling, and model selection.

How to Use This List

• Treat section A as non-negotiable setup hygiene before writing any application code.
• Revisit section C whenever a new failure mode shows up in production logs.
• Use section D when you're first choosing a model, and again whenever cost or latency becomes a concern.

A - Authentication and Setup

• Never hardcode your API key in source. Use the ANTHROPIC_API_KEY environment variable or a secrets manager, and add .env to .gitignore before your first commit.
• Fail fast when the API key is missing. Check for the key explicitly at startup and raise a clear error, rather than letting a cryptic 401 surface deep in your call stack later.
• Use separate API keys per environment. Dev, staging, and production keys let you revoke or rotate one without affecting the others.
• Pin the anthropic SDK version in your dependency file. An unpinned dependency can pull in breaking changes on a fresh install; upgrade deliberately instead.
• Construct the client once and reuse it. Build anthropic.Anthropic() at application startup or module load, not per request or per function call.

B - Request Design

• Always set max_tokens deliberately, not to an arbitrary default. Too low truncates useful output; too high wastes budget on tasks that don't need it.
• Use system prompts for persistent instructions, not the first user message. Keeping role/constraint instructions in system keeps the messages history focused on the actual conversation.
• Lower temperature for factual, structured, or deterministic tasks. Reserve higher values for genuinely creative or exploratory generation.
• Resend full conversation history on every call. The API is stateless; there is no server-side session to reference, so the client owns the conversation state.
• Prefer temperature over top_p for most tuning. Adjust one knob deliberately rather than changing both temperature and top_p at once, which makes behavior harder to predict.
• Keep prompts and system instructions in version control. Treat prompt text as code, review changes to it the same way you'd review logic changes.

C - Error Handling and Resilience

• Set a sensible max_retries on the client. The SDK's built-in exponential backoff handles 429/5xx automatically; don't disable it without a specific reason.
• Catch specific exception types, not a bare Exception. anthropic.AuthenticationError, anthropic.RateLimitError, and anthropic.BadRequestError each point to a different fix.
• Never retry 4xx errors other than 429. A malformed request fails identically on every retry; fix the request instead of retrying it.
• Add jitter to any custom retry logic. Without random variance, many clients backing off on the same schedule can resynchronize and re-trigger the same rate limit.
• Set a request timeout appropriate to your use case. Long streaming generations need a longer timeout than short, simple completions.
• Log status codes and error messages, but redact request headers. Full request dumps can leak your API key into logs if not scrubbed first.
• Monitor usage.input_tokens and usage.output_tokens on real traffic. Token counts drive both cost and context-window usage; don't fly blind on either.

D - Model Selection and Cost

• Default to Claude Sonnet 5 unless you have a specific reason to change it. It's the current balanced default across the lineup.
• Route simple, high-volume tasks to Claude Haiku 4.5. Classification, tagging, and short extraction rarely need a flagship model.
• Reserve Claude Opus 4.8 or Claude Fable 5 for genuinely hard, multi-step tasks. Using a flagship model everywhere inflates cost without a matching quality benefit for simple work.
• Centralize model ID strings as named constants. A future model swap should be a one-line change, not a search-and-replace across the codebase.
• Verify current model IDs and pricing before hardcoding them. Model names, context limits, and prices change as new versions ship; don't rely on stale documentation or training data.
• Budget for post-introductory pricing, not just launch rates. Some models ship with a limited-time intro price that increases on a announced date; plan around the steady-state rate.

E - Architecture and Maintainability

• Wrap the SDK client once your codebase has multiple call sites. A thin wrapper centralizes default model, retries, timeout, and error handling instead of repeating them everywhere.
• Keep sync and async client usage separate. Use anthropic.AsyncAnthropic inside asyncio code and anthropic.Anthropic in sync code; don't mix them in one call path.

FAQs

Related

• Understanding the Claude API Request Lifecycle - the request flow these practices protect.
• Handling Rate Limits with Exponential Backoff - the retry practices in section C, in depth.
• Claude API Error Codes and Troubleshooting Reference - the full error catalog behind section C.
• Selecting a Model: Claude Fable 5, Opus 4.8, Sonnet 5, and Haiku 4.5 - the comparison behind section D.
• Building a Reusable Claude API Client Wrapper - the pattern behind section E.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.