On this page

Troubleshooting · Block 1 · Week 2 · The second interface: APIs

Troubleshooting: when a request fails

A failed request is not a dead end. It comes back with a code, and the code names the part of your request to look at.

After the lessonGoes with the Request Builder

How to read a failure

The machine does not guess. 404 points at the address, 405 at the action, 401 at the key, 400 at the package, and 429 means too many requests. A 5xx is their machine, not yours. Change one part at a time, so you know which change fixed it.

01First, Rule Out the Network

If no request gets through at all, paste https://httpbin.org/get?text=hello into your browser's address bar. If you see JSON with "text": "hello", your connection is fine and the problem is in the request. If that fails too, the problem is your network, not your request. If httpbin itself is down, try https://postman-echo.com/get?text=hello.

02The Errors You Should Expect

Search by the code or by words from the error message. Each entry names the part of the request, the usual cause and the fix.

401Invalid API Key (Groq)

Part

key

Cause

A space or a line break was copied with the key, the key was mistyped, the header reads Authorization: gsk_… without Bearer , or the key was revoked.

Fix

Paste the key again from the source, with nothing around it. The header must read Authorization: Bearer gsk_…, with one space after Bearer. If you deleted the key in the console, create a new one.

401Key not recognised / Who are you? Key needed (Aarav)

Part

key

Cause

No key at all, a key without Bearer , a Groq key sent to Aarav (or an Aarav key sent to Groq), or a key put in the address as ?key=. The reply's hint field says which.

Fix

Create a key with POST __SITE__/aarav/keys and the package {"name": "your name"}. Send it as Authorization: Bearer aarav_…. Keys go on the envelope, never in the address: anyone can read an address.

400Add the header Content-Type: application/json

Part

package

Cause

The package was sent without saying what format it is in. Many tools default to plain text or form data.

Fix

Add the header Content-Type: application/json. In Python, passing json= to requests adds it for you.

400Can't read / Unexpected token / invalid JSON

Part

package

Cause

A missing comma between fields, a missing closing quote or brace, a comma after the last field, or curly "smart" quotes pasted from a document or a chat app.

Fix

Start from the Builder's pre-filled package and change only the text inside the quotes. Keys and text values use straight double quotes: {"workflow": "..."}. If your text contains a double quote, write it as \".

400The workflow field is missing or empty (Aarav)

Part

package

Cause

The JSON is valid but the field is named something else ("text", "description", "Workflow"), or the value is empty.

Fix

The name must match exactly, in lower case: {"workflow": "I open Jira…"}. Agreed format means both sides use the same names.

404The model does not exist or you do not have access to it (Groq)

Part

package, the model field

Cause

A typo in the model name, or a retired model. llama-3.3-70b-versatile was retired for free and developer accounts on 16 Aug 2026, and many tutorials still use it.

Fix

Use openai/gpt-oss-120b, or openai/gpt-oss-20b as the fallback. The Builder's dropdown loads only the models your key can use, so it cannot offer a retired one.

404Not found. Doors: …

Part

address

Cause

A typo in the path, a missing /aarav, /diagnosis instead of /diagnoses, or a path that does not exist on that machine. GET /aarav/diagnoses/{id} also returns 404, because this machine stores nothing yet.

Fix

Read the doors listed in the reply and copy one. GET __SITE__/aarav lists them all.

405This door takes CREATE (POST) and READ (GET)

Part

action

Cause

The address exists but does not take that action. For example, Update or Delete on /aarav/diagnoses, or a GET to Groq's chat address.

Fix

Check the reply's Allow header and pick one of those methods. Ask which CRUD action you mean first, then spell it: Create is POST, Read is GET.

429Too many requests / rate limit reached

Part

rate

Cause

More than 30 requests a minute (or 1,000 a day) on one Groq account. Usually a key shared by a group, or a script sending in a loop. Limits belong to the account, not the key.

Fix

Wait the number of seconds in the retry-after header. Each student uses their own account. Creating more keys on the same account does not help.

Blocked by CORS policy / Failed to fetch

Part

none: the browser stopped the request before it left

Cause

Browsers only let a page call another site if that site says it allows it. Groq, Aarav and httpbin allow it, so the Builder works. A page opened as a file:// path, an extension that blocks requests, a typo in the address (which reaches a site that does not allow it), or a site that does not allow browser calls at all will fail here. There is no status code, because no request reached the machine.

Fix

Check the address first. Open the Console tab: the exact message names the site. Try the same request from the Builder or with curl. If it works there, the request is fine and the browser is the blocker. Backends are not subject to CORS, which is one more reason the call to Groq moves to a backend.

The Groq reply shows only "reasoning" / the content looks empty

Part

reply package

Cause

openai/gpt-oss-120b is a reasoning model. Its reply has a reasoning field, the model's scratchpad, next to the answer. Reading the wrong field, or running out of tokens while it is still reasoning, leaves the answer empty.

Fix

Read choices[0].message.content and ignore reasoning. If content is empty and finish_reason is length, remove any small max_tokens limit and send again.

500Internal server error

Part

server: theirs, not yours

Cause

Their machine failed. /aarav/broken returns this on purpose for practice.

Fix

Nothing in your request to fix. Wait and try again, or check the service's status page. 4xx is yours; 5xx is theirs.

03The Help Post

A good help post has exactly three parts, in this order. Helpers need the code and the error. They never need your key.

Status code and error (exact text): 401 {"error":{"message":"Invalid API Key","code":"invalid_api_key"}} What I tried: Pasted the key again, checked there is a space after Bearer The request, key masked: POST https://api.groq.com/openai/v1/chat/completions Authorization: Bearer gsk_•••• Content-Type: application/json {"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "..."}]}

Use it wherever you ask for help: a forum, a colleague, or an AI chat, always with the key masked. Writing it out often shows you the fix before you send it. If you fixed it yourself, write the fix down next to it; you will meet the same error again.

04Build Guide: The Halfway Check

A self-serve check for the middle of this lesson. It covers the core of the work: your first Groq 200, reading real traffic, and your API design. Use it to see where you are, and to turn what is blocking you into one clear question, in the template below.

The milestone

Steps 1 to 8 of the Request Builder done: a 201 from Aarav's service, your break-it table, and a 200 from Groq. Plus a first draft of your API table from step 10. The full practice set comes after, before you start the next lesson.

Where are you?

Find the row that matches you, and do what it says next.

If this is you	You are	Do next
Steps 1 to 8 done and an API table drafted	On track	Check your table against the list in the practice set, then finish steps 9 and 10.
Steps 1 to 5 done, not yet through 6 to 8	Nearly there	Do step 8 first: a 200 from Groq is the step everything after it builds on. Use the Network tab guide for step 7.
A request keeps failing and you do not know why	Blocked on one part	Read the code: 404 address, 405 action, 401 key, 400 package. Search the errors above. Still stuck after 20 minutes? Fill in the template below.
Not started	Behind	Do steps 1 to 4 first, so you have a real 201 of your own to talk about. Nothing to install.

Your question template

Write your question in the template before you ask anyone. Filling it in often answers it. Use the first template for a request that fails, and the second for a question about your design.

When a request fails Where I am: Step 8 of 10 What I expected: 200 and an answer from the model What I got (status code and exact text, copied): 401 {"error":{"message":"Invalid API Key","code":"invalid_api_key"}} What I tried: Pasted the key again, checked there is a space after Bearer The request, key masked: POST https://api.groq.com/openai/v1/chat/completions Authorization: Bearer gsk_•••• Content-Type: application/json

When it is about your design Where I am: Step 10 of 10 The row I am unsure about: Create · POST · /reports · {"tickets": [...]} · 201 + report My question: Is drafting a report a Create, if I send the same tickets every week? What I think, and why: Create, because a new report exists after the request that did not exist before

Checklist at the halfway mark

Tick each item when it is ready. Ticks save on this device.

Steps 1 to 8 ticked in the Request BuilderEach step ends with a checkpoint. Tick it when you have the result.
A 201 from Aarav's serviceStep 4A screenshot of the reply with the diagnosis in it, key masked.
The break-it table filled inStep 5400, 401, 404, 405 and the 500: what you changed, the code, the part it points to.
Your own Groq key returns a 200, twiceStep 8Your own account, not a shared one. Keep both answers.
A first draft of your API tableStep 10It does not need to be finished. A draft is enough to check against the list.
One question written in the templateEven if you end up answering it yourself.

Ready to move on

0 / 6

What to have open

The Request Builder open in a tab.
Your break-it table and your API table draft, side by side.
The exact error, copied, not retyped. Have the failing request open in DevTools if your question is about traffic.
Your Groq key where you can paste it from, never in a chat or a shared doc. If it ever shows on a shared screen, revoke it and create a new one.

Before the next lesson

All five deliverables of the practice set, kept together in one note or folder.

The code names the part.Companion pages: Request Builder · keys · kit