Claude API Developer Onboarding Checklist

Onboarding a new developer onto the Claude API usually takes longer than it should. People lose an afternoon figuring out authentication, misunderstand rate limits, or ship code with no retry logic because nobody told them what errors to expect. This checklist walks through every step in order, from getting credentials to deploying a first production call, so a new team member can be productive in under an hour instead of a day.

Use it as a literal checklist: work top to bottom, check off each item, and don't skip the error-handling and testing sections just because the first request worked.

1. Get access and credentials

• [ ] Confirm who owns the Anthropic account or billing relationship (individual developer, team lead, or a shared gateway like SubToAPI).
• [ ] Generate an API key. If you're using SubToAPI, every team member gets their own sub_live_... key from the dashboard instead of sharing one Anthropic key across the team — this matters for auditing and revocation.
• [ ] Store the key in an environment variable, never in source control. SUBTOAPI_KEY or ANTHROPIC_API_KEY as a .env entry is the minimum bar.
• [ ] Verify the key works with a single curl call before writing any application code:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

If this returns a 200 with a message body, credentials are good and you can move on. If not, fix auth now — don't debug it later inside a half-built app.

2. Understand the request/response shape

• [ ] Read through the messages format once, end to end: /docs/messages. Know the difference between system, user, and assistant roles before you start building prompts.
• [ ] Know what max_tokens controls (output length cap, not input) and set it deliberately rather than copy-pasting a default.
• [ ] Understand stop_reason in the response — end_turn, max_tokens, and tool_use all mean different things and your code should branch on them.
• [ ] Try a multi-turn conversation manually (append the assistant's reply back into messages and send a follow-up) so the stateless nature of the API is clear before you build any session management.

3. Handle streaming before you need it

Most production chat UIs stream. Don't bolt this on after the fact — design for it from the start.

• [ ] Read /docs/streaming and run the example against a real endpoint.
• [ ] Confirm your HTTP client supports server-sent events or chunked responses (some older HTTP libraries buffer the whole response, which defeats the purpose).
• [ ] Write a small test script that prints tokens as they arrive, so you can visually confirm streaming is working rather than trusting status codes alone.

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4",
    max_tokens: 500,
    stream: true,
    messages: [{ role: "user", content: "Write a haiku about onboarding." }]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

4. Plan for tool use early, even if you don't need it yet

• [ ] Read /docs/tools even if the first project doesn't call a function. Tool use changes the response shape (stop_reason: "tool_use") and if your error handling doesn't account for it, it'll break the moment someone adds a tool six months from now.
• [ ] Decide where tool execution happens (your backend, not the client) and write that into your architecture notes before code gets written.

5. Build real error handling, not a try/catch wrapper

This is the step most checklists skip and most incidents trace back to.

• [ ] Handle 429 (rate limited) with exponential backoff, not a fixed retry delay.
• [ ] Handle 401/403 explicitly — these usually mean an expired or revoked key, and should alert a human, not retry silently.
• [ ] Handle 5xx with retries capped at 2–3 attempts, with jitter.
• [ ] Log stop_reason: "max_tokens" as a warning in your own telemetry — it usually means truncated output that looks fine in testing but breaks in production with longer inputs.
• [ ] Set a request timeout. Don't let a hung connection block a user-facing request indefinitely.

6. Set up rate limit and cost visibility

• [ ] Know your plan's rate limits before you hit them in a demo. Check /pricing if you're unsure which tier you're on.
• [ ] If multiple developers or services share one account, set up per-key or per-user tracking so a runaway script doesn't eat the whole team's quota. SubToAPI issues separate keys per team member for exactly this reason, so usage and limits are visible per person, not just account-wide.
• [ ] Set a soft internal budget alert — even a daily Slack message with token counts — before the first production launch, not after the first unexpectedly large invoice.

7. Write one test that exercises the full path

• [ ] One integration test that sends a real request (against a sandbox or low-cost model) and asserts on response shape, not just a 200 status.
• [ ] One test that simulates a 429 and confirms your retry logic actually backs off instead of hammering the API.
• [ ] One test that simulates stop_reason: "max_tokens" and confirms your UI doesn't silently show a cut-off response as if it were complete.

8. Get the new developer self-sufficient

• [ ] Point them at /docs/quickstart for a working end-to-end example they can run locally in under 10 minutes.
• [ ] Give them their own API key rather than a shared one — on SubToAPI this is a dashboard click, under Solo (€9), Team (€19/seat), or Scale (€49/seat) depending on team size.
• [ ] Confirm they know where to check usage, revoke a key, and read error logs without needing to ask you.

If every box above is checked, a new developer has working credentials, understands streaming and tool use, has real error handling in place, and knows how to see their own usage — which is the actual bar for "onboarded," not just "made one API call."

questions

Do I need a separate API key for every developer on my team? Yes, if you want usable audit logs and the ability to revoke one person's access without breaking everyone else's. Shared keys make incident response much harder.

What's the single most common onboarding mistake? Skipping error handling for rate limits and truncated responses (stop_reason: "max_tokens"). Code works fine in a demo and then breaks the first time a real user sends a long input.

Where should I start if I've never called the Claude API before? Run through /docs/quickstart first, confirm a basic request works with curl, then move on to streaming and tool use once the fundamentals are solid.