Command Palette

Search for a command to run...

Hectal
Phase 1Beginner2 of 16 in AI Frontend

Calling a Model over HTTP

The chat request and response, every state of one request on screen, every HTTP failure and what to tell the user, timeouts and retries, and your own server route.

Phase 0 showed the three hops of an AI feature. This phase makes the middle one solid. You will learn what a chat request and a chat response really contain, field by field, and what each field means for your screen: the roles, the text, the reason an answer stopped, and the token counts.

Then you will learn what goes wrong and what to do about it. Every request lives in one of four screen states (idle, loading, success, error). Every failure has a real symptom: a 400, a 401, a 429 with a wait time, a 500, a gateway that answers with a web page instead of JSON, a phone that is offline. Each one deserves its own honest message, and none of them should ever show the provider's raw words to a visitor.

You will add timeouts, retries with backoff and jitter, and the rule for requests that must never be repeated. You will write the server route that holds your secret key and distrusts the browser. Every example runs real browser code against a scripted stand-in model, so it works with no account and prints the same thing every time. The phase ends with Mitra v1: a shop assistant that answers reliably, with every state handled and no streaming yet. (Streaming arrives in Phase 2, on top of this foundation.)

0/6 · 0%
6 topics ~3 h 19 code blocks & diagrams
Start with the first topic
1
1.1

The Chat Request and Response

A chat request is a JSON list of messages, each with a role. The response is JSON too: the answer text, the reason the answer stopped, and token counts. Reading all three fields correctly is what separates a finished answer from a cut-off one.

27 min 4 code practice

2
1.2

Loading, Empty, Success and Error States

One request moves through four screen states: idle, loading, success and error. Keep them in a single variable, make every state look different, and guard the submit against empty input, very long input and double sends.

29 min 3 code practice

3
1.3

When the Request Fails

Every failure has a different cause and deserves a different message: a bad request, a missing key, a rate limit with a wait time, a broken server, a gateway page that is not JSON, or no connection at all. Read the error body safely, and never show the provider's raw words to a visitor.

30 min 3 code practice

4
1.4

Timeouts and Retries

Give every request a time limit, retry only the failures that can succeed next time, wait longer between each try with a little randomness, stop after a few attempts, and never repeat a request that has already had a side effect unless it carries an idempotency key.

29 min 3 code practice

5
1.5

Your Server Route and Secrets

The browser never calls the model provider directly. It calls your own server route, which holds the secret key, checks the request, decides the model and system prompt itself, limits size and rate, and returns only a safe answer.

34 min 4 code practice

6
1.6

Build: Mitra Answers Reliably

Mitra v1 asks through your own route, gets a whole answer as JSON, and handles every outcome: a complete answer, a cut-off one, a blocked one, a timeout, a rate limit, a broken server, no connection. It retries what is worth retrying and never shows the provider's words.

36 min 2 code practice

Practise this phase

Hands-on exercises: write the code, see your page live, and press Check to have it tested automatically.

1

Read the Reply

The route /api/chat answers with the usual chat JSON. When #ask is clicked, send the request and show three things: the reply text in #answer, the finish reason as Finish: stop in #finish, and the token total as Used 50 tokens in #usage (use the real number from the response).

Beginner
2

Cut Off, Blocked and Complete

The stand-in model answers three questions in turn: the first answer is cut off at the length limit, the second is blocked by a filter and has no text, the third is complete. Every call is HTTP 200.

Beginner
3

Empty Input and Double Sends

This form sends a question to the route, which answers Answer 1, Answer 2 and so on, so you can count how many requests reached it. Two things are wrong.

Beginner
4

Friendly Errors

The route fails in a different way each time you click #ask: a 429 (with Retry-After: 5), a 500, a 401 whose body contains a made-up key, a 502 whose body is an HTML page, and finally a success. Right now the page prints whatever text the server sent.

Intermediate
5

Time Limit and Try Again

The first request to this route takes 600 ms; later ones are instant. Add a time limit of 200 ms with AbortSignal.timeout(200). When it fires, show Mitra is taking too long. Please try again. in #error and show the #retry button (it starts hidden). Other failures show Cannot reach Mitra. Check your connection.

Intermediate
6

Write a Safe Route

Write the route handler for /api/chat. The checks call it directly with different requests. A valid request must return status 200 and JSON { model, roles }, where model is always provider/model-name and roles is the list of roles sent to the provider, joined by commas. The provider call is already written for you (callProvider).

Intermediate