HASZB_AIHASZB_AI

Search across courses, lessons, glossary terms, prompts and tools.

Menu

Stage 7 · APIs, MCP & Connectors

How an API call works

Request, response, status code. Four ideas that explain every integration you will ever debug.

7 min read

In this lesson

  • Read an HTTP request and response
  • Interpret status codes correctly
  • Recognise why most integration bugs are contract mismatches

An API is how one program asks another to do something. Nothing about it is unique to AI — but you cannot reason about tool calls, connectors or MCP without it.

Request and response

A request has four parts:

  • Method — what kind of operation. GET retrieves, POST creates, PUT replaces, PATCH modifies, DELETE removes.
  • URL — what you are addressing: https://api.example.com/v1/orders/4471
  • Headers — metadata about the request, including authentication and content type.
  • Body — the data being sent, on methods that carry one. Usually JSON.

A response has three:

  • Status code — how it went.
  • Headers — metadata, including rate limit information.
  • Body — the result, usually JSON.

Status codes are the first thing to read

The first digit tells you who is responsible:

  • 2xx — success. 200 fine, 201 created.
  • 4xx — you are at fault. 400 malformed, 401 not authenticated, 403 authenticated but not allowed, 404 no such thing, 429 too many requests.
  • 5xx — the server is at fault. 500 internal error, 503 unavailable.

That split matters for retries. 4xx should not be retried unchanged — the same bad request will fail identically. 5xx and 429 should be retried, with a delay, because the condition is temporary.

The contract is the hard part

Networks are mostly reliable. What breaks integrations is the contract: the agreement about field names, types, required fields and shapes.

Classic failures, all of which are total:

  • One side sends user_id, the other expects userId
  • A field is a string in one system and a number in the other
  • A field is optional in the documentation and required in practice
  • The API returns a single object where you expected an array of one

This is exactly why tool definitions for models are written as strict schemas. The schema is the contract, made explicit.

Idempotency, briefly

An operation is idempotent if doing it twice has the same effect as doing it once. GET and DELETE usually are. POST usually is not — sending it twice creates two records.

This matters the moment you add retries. A retry after a timeout may repeat an operation that actually succeeded. For anything that creates or charges, use the API's idempotency key if it offers one, so a repeat is recognised rather than duplicated.

Why this lesson exists

When an agent calls a tool, this is what happens underneath. A tool that "does not work" is almost always a request the model formed wrongly, a permission it does not have, or a response shape nobody handled. Being able to read the exchange turns a mysterious agent failure into an ordinary bug.