AI APIs Explained: Authentication, Tokens, Costs, and Error Handling

An AI API is an HTTP interface that sends your input to a hosted model and returns the model’s output, with every request authenticated by a credential and billed by tokens. Understanding four things — how requests are authenticated, how text becomes tokens, how tokens become money, and how failures are reported — is enough to move from pasting a snippet out of a docs page to operating an AI feature you can afford, debug, and defend.

This guide is the central reference for that path. It is written for a technically curious beginner who can already make an HTTP request in Python or JavaScript and now needs AI features to be reliable, affordable, and safe. The boundary is deliberate: it covers hosted provider APIs (OpenAI, Anthropic, Gemini, and OpenAI-compatible endpoints) and notes where local runtimes change the picture. It does not cover model training, fine-tuning pipelines, or the internals of transformer architecture.

The request loop: what actually happens between your code and the model

The loop is short and worth memorizing. Your text goes out over plain HTTPS, gets chopped into tokens, the model reads those tokens and writes tokens back, and you are billed for both directions. That single sentence from a KodeKloud explainer on LLM APIs is the whole system in miniature, and almost every practical problem you will hit — a surprising bill, a truncated answer, a mysterious 400 — traces back to one of its stages.

Four properties of that loop shape everything else:

• It is stateless. The model does not remember your last request. Anything the model should “know” for this call — system instructions, prior turns, retrieved documents, tool definitions — must travel in the request body. Conversation memory is something your application assembles, not something the endpoint retains.
• It is metered in both directions. Input tokens and output tokens are counted and priced separately, and output is usually the more expensive direction.
• It is asynchronous in cost, synchronous in latency. You pay after the fact, but you wait in real time. A request that takes 40 seconds is a request your user is staring at.
• It fails loudly and specifically. A bad credential, a malformed body, an oversized context, and a rate limit all produce different status codes with different correct responses.

It helps to separate three things that beginners often conflate. A chat web interface is a client of these same APIs — it just hides the key, the token counter, and the error codes from you. A local runtime such as Ollama, llama.cpp, or vLLM exposes an OpenAI-compatible endpoint on your own machine, which looks almost identical to a hosted API but bills in electricity and hardware instead of dollars per token. And an SDK is a thin wrapper that builds the HTTP request for you; when something breaks, the underlying request and response are still what matters.

The anatomy of a single call is therefore worth knowing in raw form:

curl https://api.example-provider.com/v1/responses 
  -H "Authorization: Bearer $AI_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"model":"MODEL_ID","input":"Hello","max_output_tokens":32}'

An endpoint URL, an authentication header, a JSON body naming the model and the input, and a JSON response containing output plus a usage report. The Sefism LLM APIs cheat sheet organizes the whole feature-building path into eight chapters and 56 concepts — tokens and context windows, prompts and roles, streaming, structured output, images as input, tool calling, embeddings and retrieval, caching, batching, cost, evals, tracing, and security — and publishes the same ideas in OpenAI, Anthropic, and Gemini editions using each provider’s official Python SDK. That structure is a useful map of the territory this article covers at pillar depth.

Authentication: the API key is a spending credential

The most important sentence about authentication is also the least technical: an API key is a password that spends money. It authenticates you and authorizes the charge, which is why a leaked key is a financial problem, not merely a security one. Treat it with the seriousness you would give a cloud billing credential, because that is what it is.

Providers differ in the mechanics but not the concept. OpenAI-style endpoints conventionally use a bearer header, Authorization: Bearer YOUR_KEY. Anthropic uses an x-api-key header. Some Google Gemini surfaces accept the key as a query parameter, which is convenient for a quick test and a bad habit for production because URLs end up in logs, browser history, and proxy records. Most providers also expose an organization or project identifier that scopes which account the spend lands on.

Storage and handling rules that prevent most incidents

1. Never hardcode a key in source. Read it from an environment variable or a secrets manager. A key committed to a repository is compromised the moment the repository is cloned, forked, or made public — even if you delete the commit later, the value may persist in history and in forks.
2. Never ship a key to a browser or a mobile client. Anything in client-side JavaScript or an app bundle can be extracted. If a front-end needs AI output, it should call your own server, and your server should hold the key.
3. Use separate keys per environment and per project. A development key and a production key should not be the same string. When something goes wrong, you want to revoke one without taking down the other, and you want the usage dashboard to tell you which workload is responsible.
4. Set spend limits and alerts at the account or project level. This is the single cheapest guardrail available. It converts a runaway loop from a catastrophe into an inconvenience.
5. Rotate on a schedule and on suspicion. Rotation is boring and effective. If a key has ever been pasted into a chat, a ticket, a screenshot, or a shared notebook, rotate it.

Responding to a leaked key

The response sequence is short. Revoke the key first, then investigate. Check the usage dashboard for requests you did not make, look for unfamiliar models or unusual token volumes, and review any audit log the provider offers. Then issue a replacement, update the secret store, and confirm that the old key now returns an authentication error. Do not spend time trying to determine whether the leak was exploited before you have revoked — revocation is cheap and reversible; unauthorized spend is neither.

The local exception

Local runtimes usually have no authentication at all, because the endpoint listens on localhost and only your machine can reach it. OpenAI-compatible local servers often accept a dummy value in the authorization header simply because client libraries require the field to be present. This is one of the genuine advantages of local inference: there is no credential to leak and no third party to bill. It is not a security free pass — if you expose that port to a network, you have created an unauthenticated compute endpoint, which is its own problem.

Tokens: the unit of work and the unit of billing

Tokens are the billing unit, not words. Before a model sees your text, a tokenizer splits it into subword units drawn from a fixed vocabulary. Common words may be a single token; unusual words, identifiers, code, and non-English text often fragment into several. The practical consequence is that your intuition about length is unreliable: the same sentence can be counted as anywhere from 11 to 94 input tokens depending on which model read it.

That variance is not a rounding error. It means a cost estimate built from character counts can be wrong by an order of magnitude across providers, and it means switching models can change your bill even if your prompts do not change at all.

Input tokens, output tokens, and the invisible ones

Every response reports usage. Input tokens cover everything you sent: system instructions, conversation history, retrieved context, tool schemas, and the user’s message. Output tokens cover everything the model produced — and that is where a common surprise lives. Some models generate internal reasoning before producing a visible answer, and those reasoning tokens are billed as output even though you never see them. One documented case billed 497 output tokens for 283 characters of visible text, because 445 of those tokens were invisible reasoning.

The lesson is not that reasoning models are a trap. It is that “output tokens” and “visible answer length” are different quantities, and a cost model that assumes they are equal will be wrong in a direction that hurts.

The context window is working memory, not knowledge

The context window is the maximum number of tokens the model can consider in a single request — input plus output combined. It is working memory for one call, not a store of facts the model retains. Exceed it and you get a hard error, not a polite summary or a silent truncation. That distinction matters because it determines your failure mode: an oversized request fails visibly and immediately rather than degrading quietly.

Everything competes for that window:

• System or developer instructions, which may be long and are sent on every call.
• Conversation history, which grows with every turn unless you manage it.
• Retrieved documents in a RAG pattern, which are often the largest single contributor.
• Tool and function definitions, whose JSON schemas are counted as input tokens.
• The model’s own output, including any hidden reasoning.

Managing the window is therefore a design activity, not a tuning afterthought. The common strategies are truncation of the oldest turns, summarization of history into a compact running note, retrieval that fetches fewer and better chunks rather than more, and choosing a model with a larger window only when the task genuinely needs it — because larger windows are usually priced accordingly.

Estimating before you send

Provider tokenizer tools and open tokenizer libraries let you count tokens for a specific model rather than guessing. A rough rule of thumb — on the order of four characters per token for ordinary English prose — is useful for sanity checks and useless for budgeting, because it breaks down on code, structured data, and non-English text. The reliable workflow is: measure with the tokenizer for the model you actually use, then reconcile against the usage numbers the API returns, then use the reconciled figure for planning.

Parameters that change both behavior and the bill

A handful of request parameters do most of the work, and each has a cost or reliability consequence.

• Model identifier. The single largest cost lever you have. The same question can cost dramatically different amounts depending on which model answers it — one measurement found a 170x spread between the priciest and cheapest model for the same question, in the same minute.
• Maximum output tokens. A hard ceiling on generation. Setting it is a cost guardrail and a latency guardrail at the same time. Leaving it unset on a model capable of long outputs is how a single request becomes an expensive one.
• Temperature. Controls how surprising the wording is, not how smart the answer is. It is the parameter most often blamed for problems it did not cause, and a caching layer can make it look as though temperature does nothing at all.
• Streaming. Delivers tokens as they are produced rather than all at once. It does not change the token count or the price; it changes perceived latency and it changes how errors arrive, because a failure can now occur after you have already displayed partial output.
• Structured output and tool calling. Constrain the model to produce a schema-conformant object or to request a function. The schema itself is input tokens, and the constrained output is still output tokens.
• Caching directives. Some providers let you mark stable prefixes — a long system prompt, a fixed document — so repeated requests are billed at a reduced cached-input rate. This is one of the few cost optimizations with no quality tradeoff, but it only helps when the prefix is genuinely stable.

How cost is actually calculated

Cost is a product of four things: input tokens, output tokens, the per-token rates for the model you chose, and any discounts or surcharges that apply. Because input and output are priced separately and output is typically the more expensive direction, a workload that generates long answers costs more than a workload that reads long inputs and answers briefly — even when the total token count is similar.

An illustrative estimate, with its assumptions stated

Suppose a support-triage feature sends a 600-token system prompt, a 900-token ticket, and a 300-token conversation history, and asks for a 150-token structured classification. That is roughly 1,800 input tokens and 150 output tokens per call. At 10,000 calls per day, that is 18 million input tokens and 1.5 million output tokens daily.

This example is deliberately hypothetical: the token counts are estimates, not measurements, and no prices are quoted because rates change and vary by model. To turn it into a real budget, substitute the current published rates for your chosen model, multiply, and then add a margin for retries, hidden reasoning tokens, and the fact that real inputs are messier than the estimate. Re-run the arithmetic whenever you change models — the model choice moves the answer more than any prompt tweak.

Levers that reduce cost without reducing quality

• Trim the system prompt. It is sent on every request. A 600-token instruction block that could be 200 tokens is a permanent 3x tax on that portion of your input.
• Use prompt caching for stable prefixes. Pay the cached rate for the parts that never change.
• Route by difficulty. Send simple classifications to a small, cheap model and reserve the expensive model for genuinely hard cases. This is a routing decision, and it should be validated with an evaluation set rather than assumed.
• Cap output tokens. Especially for structured outputs, where the correct answer has a known maximum length.
• Batch where the provider supports it. Batch endpoints typically trade latency for a discount, which is a good trade for overnight jobs and a bad one for interactive features.
• Cache your own results. If the same input recurs, storing the answer locally costs nothing per token.

Watching the meter

Three habits keep cost visible. First, log the usage object from every response alongside a request identifier, the model, and the latency; this turns cost from a monthly surprise into a per-feature measurement. Second, set provider-side budget alerts so that a runaway loop pages you the same day rather than the same month. Third, track cost per successful task rather than cost per call — a cheap model that fails and gets retried three times is not actually cheap.

The local alternative to per-token pricing

Running a model locally removes the per-token meter entirely. The marginal cost of a request becomes electricity and hardware amortization, which makes high-volume, low-variance workloads economically attractive and makes the cost model predictable. The tradeoffs are real: capability is usually lower than a frontier hosted model, throughput depends on your GPU or CPU, and memory is the binding constraint. When estimating local memory, remember that model weight size is not the total — the KV cache grows with context length, and runtime overhead sits on top. Quantization shrinks the weights, not the KV cache.

Error handling: reading the failure, then deciding whether to retry

Errors are where a demo becomes a product. The core discipline is classification: some failures are permanent and retrying them just wastes money and time, while others are transient and retrying is exactly right. Retrying the wrong class is a common cause of both outages and inflated bills.

A retry pattern that does not make things worse

For the retryable classes, the standard pattern is bounded exponential backoff with jitter:

import random, time

for attempt in range(5):
    try:
        return call_api(payload)
    except RateLimitError:
        delay = min(2 ** attempt, 30) + random.uniform(0, 1)
        time.sleep(delay)
    except ServerError:
        delay = min(2 ** attempt, 30) + random.uniform(0, 1)
        time.sleep(delay)

Three details matter more than the loop itself. Jitter — the random component — prevents a fleet of clients from retrying in lockstep and re-creating the overload that caused the 429. A cap on attempts prevents a permanent failure from becoming an infinite spend. And a total time budget, enforced across all attempts, prevents a user-facing request from hanging for minutes while it politely retries.

Beyond the loop, three patterns handle the cases backoff cannot. A circuit breaker stops sending traffic to a provider that is clearly down, so you fail fast instead of queueing. A fallback model lets a request continue on a secondary provider or a smaller local model, at some cost in quality. Graceful degradation means the feature does something useful without the model — returning a template, deferring to a queue, or showing the raw input with a note — rather than showing an error to the user.

What to log, and what never to log

Log the request identifier the provider returns, the model, the token counts, the latency, the outcome, and the error code. That set is enough to reconstruct cost, diagnose patterns, and correlate a user complaint with a specific call. Never log the API key, and be careful with full prompt and response bodies: they frequently contain personal data, and in many jurisdictions storing them creates obligations you did not intend. If you must retain them for debugging, redact and set a retention period.

A practical first path: one call, a receipt, then a guardrail

The fastest way to internalize all of this is to make one call and read the receipt. The sequence below assumes you can run Python and set an environment variable. It is a suggested setup, not a tested environment; check the current SDK signature against your provider’s documentation before relying on it.

1. Create a scoped key. Generate an API key inside a dedicated project, and set a spend limit and an alert on that project before you write any code.
2. Store it outside your code. Put it in an environment variable or a secrets manager. Confirm it is not in your repository and not in your shell history.
3. Make one minimal call. The OpenAI Responses API, as documented in the Sefism cheat sheet’s OpenAI edition, uses client.responses.create with input, instructions, and output_text:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["AI_API_KEY"])

resp = client.responses.create(
    model="MODEL_ID_FROM_PROVIDER_DOCS",
    instructions="You are a concise technical editor.",
    input="Summarize this paragraph in one sentence: ...",
    max_output_tokens=120,
)

print(resp.output_text)
print(resp.usage)

4. Read the usage numbers. Compare the reported input tokens against your own guess. The gap between the two is the most useful calibration you will get all week.
5. Add error classification. Wrap the call so that a 401, a 400, a context-length error, and a 429 each take a different path. Start with the table above.
6. Add a cost guardrail. Cap max_output_tokens, log the usage object per request, and confirm the provider-side alert fires when you deliberately exceed a low threshold in a test project.
7. Add a human review point. Before anything the model produces reaches a user or a published page, decide who looks at it and how often. For low-risk internal tooling, sampling may be enough. For public content, review is not optional.

Observable success checks: the call returns text; the usage object reports non-zero input and output tokens; a deliberately corrupted key produces an authentication error rather than a retry storm; a deliberately oversized input produces a context-length error you can identify; and your log contains one line per request with model, tokens, latency, and outcome.

Worked example: an AI draft summarizer for WordPress

A concrete application ties the pieces together. Suppose a site wants an automatically generated summary and tag suggestion for each draft post, with a human editor approving before publication.

Input. The post content, plus a fixed instruction block describing the desired summary length and tag vocabulary.

Process. The plugin runs server-side. It reads the API key from a constant defined in wp-config.php or from a secrets store — never from a block, a shortcode attribute, or anything that reaches the browser. It sends the request through WordPress’s HTTP API, which means setting an explicit timeout rather than relying on the default, and handling a WP_Error return value as a first-class outcome rather than assuming a response body exists.

Output. A summary string and a set of tags, written into post meta rather than directly into the post body, so nothing is published by accident.

Human review point. The editor sees the suggested summary and tags in the sidebar and accepts, edits, or discards them. Nothing is written to the published post until that action occurs.

Operational details that prevent the usual failures. Run generation on a queue or a scheduled event rather than synchronously on save, so a slow model call does not block the editor’s request. Guard against duplicate processing with a post-meta flag that records whether generation has already run for this revision. Log the token counts per post so you can see which long articles are driving cost. And on failure, leave the draft untouched and record the error — a failed summary should never corrupt the post.

This pattern generalizes: keep the credential server-side, keep the model output in a staging field, keep a human in the loop, and keep a log. Those four rules cover most of the ways an AI integration into a content system goes wrong.

Where local models change the equation

Local inference is not a different conceptual model — it is the same request loop with the meter moved. A local server exposes an OpenAI-compatible endpoint, so your client code barely changes:

curl http://localhost:11434/v1/chat/completions 
  -H "Authorization: Bearer ollama" 
  -H "Content-Type: application/json" 
  -d '{"model":"MODEL_YOU_PULLED","messages":[{"role":"user","content":"Hello"}]}'

What changes is the failure profile and the cost structure. Authentication is typically absent or a placeholder. The context window is bounded by available memory rather than by a provider’s configuration, and the KV cache grows with context length, so a long conversation can exhaust VRAM even when the model weights fit comfortably. The characteristic errors are different too: model load failures, out-of-memory conditions, and very slow first-token latency rather than 429s and 5xxs. In exchange, there is no per-token bill, no data leaving your machine, and no rate limit imposed by someone else.

For a team deciding between the two, the honest framing is that hosted APIs buy capability and operational simplicity with money and data exposure, while local inference buys privacy and predictable marginal cost with hardware, capability limits, and operational burden. Many production systems use both: a local model for high-volume, low-difficulty work and a hosted model for the hard cases.

Evaluating whether the integration actually works

Cost and correctness are separate questions, and both need an answer before launch.

• Accuracy. Build a small labeled set of representative inputs with known good outputs, and measure agreement. Twenty to fifty examples is enough to catch gross errors; it is not enough to claim statistical confidence, and you should say so.
• Cost per successful task. Divide total spend by tasks that produced an acceptable result, not by calls made. This is the number that reflects reality once retries and failures are included.
• Latency distribution. Track percentiles, not averages. A mean of two seconds with a 95th percentile of forty seconds is a different product.
• Failure rate by class. A rising 429 rate means you need quota or backoff tuning. A rising 400 rate means a payload or schema change broke something.
• Privacy and data handling. Know what leaves your environment, how long the provider retains it, and whether your inputs contain personal data. If they do, redaction or a local model may be required.
• Assumption review. Every cost estimate rests on token counts, call volumes, and prices. Write those assumptions down next to the number so that the next person can see which one changed.

Troubleshooting: common mistakes and how to diagnose them

Next steps and where to go deeper

The immediate next action is the one described above: make a single call, print the usage object, and reconcile the reported token counts against your own estimate. That one exercise converts every abstraction in this article into a number you have personally seen.

From there, a reasonable progression is: add error classification and bounded retries; add a cost guardrail and a per-request log; build a small evaluation set and measure accuracy and cost per successful task; then decide whether any part of the workload belongs on a local model. Each step answers a specific question, and each one is small enough to finish in an afternoon.

For readers who want a structured reference rather than a narrative, the Sefism LLM APIs cheat sheet covers the same concepts as short cards across eight chapters, with separate OpenAI, Anthropic, and Gemini editions so the same idea can be seen in the SDK you actually use. For a readable walkthrough of the request loop and the billing mechanics, the KodeKloud explainer on how LLM APIs work is a good companion piece. Neither replaces reading your provider’s own documentation for current model identifiers, prices, and limits, which change on their own schedule.

If you are working through this for the first time, the community is the fastest way past a stuck error. When you post, include what you are trying to build, your environment and SDK version, the exact error message or status code, the smallest request that reproduces it, and what you already tried. That combination lets someone else reproduce your situation instead of guessing at it — and it is the same information you would want if you were debugging it yourself.