APIs Explained: Requests, Auth and Errors

10 minute read · Last updated 2026-10-31 · Written and reviewed by the Code.House editorial team

An API is a contract: send a request shaped a particular way and get a predictable response. Almost every integration task — payments, maps, email, AI models — is the same handful of ideas repeated with different field names.

Requests and responses

An HTTP request has a method, a URL, headers and sometimes a body. The method states intent:

The response carries a status code. The first digit is the summary: 2xx worked, 3xx redirects, 4xx means your request was wrong, 5xx means the server failed. The ones worth memorising are 200, 201, 204, 400, 401, 403, 404, 409, 422, 429 and 500.

Making a call

// JavaScript
const res = await fetch('https://api.example.com/v1/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({ item: 'A-100', quantity: 2 }),
});
if (!res.ok) throw new Error(`API error ${res.status}`);
const order = await res.json();

# Python
import requests

res = requests.post(
    "https://api.example.com/v1/orders",
    json={"item": "A-100", "quantity": 2},
    headers={"Authorization": f"Bearer {token}"},
    timeout=15,
)
res.raise_for_status()
order = res.json()

Always set a timeout. Without one, a hung connection can block a process indefinitely.

Authentication

• API key — a single secret string in a header. Simple, and suitable for server-to-server calls only.
• Bearer token — a token issued after a login, sent on each request, usually short-lived.
• OAuth 2 — a flow where a user grants your application limited access to their account on another service, without sharing their password.

Keys belong in environment variables, never in front-end code or a committed file. Anything shipped to a browser is public, however obfuscated. When a third-party API must be called from a page, route it through a small server function that holds the key.

Rate limits, retries and idempotency

A 429 response means you are sending too fast. The response usually includes a Retry-After header. Back off exponentially — wait 1s, then 2s, 4s, 8s with a little random jitter — instead of retrying immediately in a loop.

Retrying a POST can create duplicates. Well-designed APIs accept an idempotency key: a unique value you generate per logical operation, so a repeated request with the same key returns the original result instead of creating a second record. Payment APIs almost always support this, and using it is the difference between one charge and two.

Designing your own endpoints

If you publish an API, a few conventions save your users time: plural nouns for collections (/invoices), the identifier in the path (/invoices/123), filtering in the query string (?status=unpaid&limit=50), and a version in the path (/v1/) so you can change shape later without breaking existing clients.

Return errors as structured data, not prose. A body like {"error": {"code": "insufficient_funds", "message": "..."}} can be handled programmatically; a plain sentence cannot.

Common questions

REST or GraphQL?

REST is simpler to cache, debug and operate, and fits most projects. GraphQL pays off when many different clients need different shapes of the same data and over-fetching is a real cost.

How do I test an API without writing code?

Command-line curl, or a client such as Hoppscotch, Bruno, Insomnia or Postman. Reproducing a call as a curl command is also the fastest way to share a bug report.

Keep reading

Spotted something out of date? Send a correction — guides are revised rather than quietly deleted.