API and Integration Essentials
Request anatomy
The Messages API is the core integration surface. A request includes a model, a max_tokens value, a system prompt, and a list of messages alternating user and assistant roles. The API is stateless: you must resend the conversation history each turn. Streaming returns tokens incrementally so users see progress. Tool use lets the model request a function call with structured arguments; your application executes it and returns the result. Structured output or strict JSON is best requested with a schema plus validation.
Reliability
Production integrations need retries with exponential backoff and jitter for 429 (rate limit) and 5xx errors, but not for 400-level validation errors. Keep API keys server-side; never embed them in client code. Set timeouts, log request IDs, and cap max_tokens to control cost. Validate model output and tool arguments before acting on them.
Traps
Candidates often place the system prompt inside the first user message, which weakens instruction priority. Another trap is forgetting max_tokens is required and then being surprised by truncation. Do not assume the API remembers prior turns. Do not retry non-idempotent tool actions blindly-use idempotency keys or confirmation.
Worked example
A 429 response should trigger a bounded retry (for example, three attempts with exponential backoff); a 400 invalid-schema response should fail fast and surface the error, because retrying identical input will not help.