# Requests and responses — HTTP

> **What you will learn**
> The shape of what the web actually exchanges, four status codes worth telling
> apart, why headers carry credentials, and what HTTPS does and does not protect.

## One round trip is the whole thing

Whatever you do in a browser, and whenever an agent calls a tool, the same thing
happens underneath. **A request goes out and a response comes back.** The rules
for that are called HTTP.

```mermaid
graph TD
  A["request<br/>what · where · who"] --> B["server"]
  B --> C["response<br/>status code + content"]
```

```
request    GET /api/v1/tasks HTTP/1.1
           Host: localhost:27777
           Authorization: Bearer tt_••••

response   200 OK
           Content-Type: application/json

           {"tasks": [ … ]}
```

## Four pieces of a request

| Piece | Meaning | Example |
|---|---|---|
| **Method** | what you want done | `GET` `POST` |
| **URL** | where | `/api/v1/tasks` |
| **Headers** | extra information, identity | `Authorization: Bearer …` |
| **Body** | what you are sending | `{"prompt": "…"}` |

### Four methods are enough

| Method | What it does | Reversible |
|---|---|---|
| `GET` | fetch | changes nothing |
| `POST` | create | **changes things** |
| `PUT`·`PATCH` | modify | **changes things** |
| `DELETE` | remove | **not reversible** |

**Those bottom three rows are the same criterion used to place
[approval gates](/guide/ha-guardrails).** Separating tools that read from tools
that write starts here — [Tools are permissions](/guide/mcp-security) tells the
same story from the tool side.

## The first line back — status codes

Three digits. **The first digit gives you the character.**

| Code | Meaning | What to fix |
|---|---|---|
| **200** | fine | — |
| **401** | I do not know who you are | **the key** — missing or wrong |
| **403** | I know you, you may not | **permissions** — grant them |
| **404** | no such address | **the address** — typo or removed |
| **429** | too many calls | **rate** — wait and retry |
| **500** | the server broke | **not your fault** — logs are on their side |

**Telling 401 from 403 pays for itself daily.** 401 is a key problem, 403 is a
permission problem, and different people fix them. Re-issuing keys against a 404
is the most common wasted afternoon.

## Why headers hold the identity

URLs are recorded **verbatim** in browser history, server logs and middleboxes.
So secrets do not go in the address; they ride in a header.

```
✓ Authorization: Bearer tt_abc123…      header — conventionally not logged
✗ /api/v1/tasks?token=tt_abc123…        address — recorded everywhere
```

It is why [Attaching a database](/guide/cn-database) puts connection strings in
headers and why [API keys](/guide/cn-api) travel that way. **`Bearer`** is just
the conventional word for "whoever holds this key".

## What HTTPS protects — and what it does not

When an address starts with `https://`, **the content in transit is
encrypted.** Intercepting it yields nothing readable.

```
✓ protected — eavesdropping · tampering · being lured to a fake server
✗ not protected — what the receiving server does with your data afterwards
```

**"It is HTTPS, so it is safe" is half right.** It secures the journey only.
Whether the destination deserves the data is a separate judgement — the one
[security review](/guide/cn-security) exists to make.

## Common misconceptions

### "A 500 error — did I do something wrong?"

**Usually not.** The 500 range means the server failed to process it. Still,
sending a strange value can be what broke it, so look at what you sent once.

### "If a request fails, can I just send it again?"

`GET` is safe to repeat. **`POST` is not** — you may simply have missed the
response while the server already created the thing, so a retry creates it
twice. [Driving work over REST](/guide/ht-rest-api) treats this separately.

---

## Check yourself

**1. What is the difference between 401 and 403?**

<details>
<summary>Answer</summary>

**401 means "I do not know who you are" (key problem); 403 means "I know you but
you may not" (permission problem).** Different fixes.
</details>

**2. Why put a secret key in a header rather than the URL?**

<details>
<summary>Answer</summary>

**Because URLs are recorded** — browser history, server logs, middleboxes.
</details>

**3. What does HTTPS not protect?**

<details>
<summary>Answer</summary>

**What the receiving server does with the data.** It secures the journey, not
the destination's intentions.
</details>

---

Next, the same round trip made for programs instead of people →
[What an API is](/guide/it-api)