REST hibatörzsek és kérésazonosítók (request id-k), MCP tool hibák, valamint biztonságos build újrapróbálkozások.

A REST hibák típusosak

Egy REST gépi hívó – API kulcs vagy csatlakoztatott alkalmazás – strukturált hibát kap, nem pedig olyan szöveges üzenetet, amelyet substring-egyezés alapján kellene azonosítani:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "insufficient scope: build:write required",
    "request_id": "req_2ede35dd-b5ad-4f06-90e9-7859d799f156"
  }
}

Az elágazás alapja legyen a type és a code, soha ne a message – az üzenet emberek számára készült, és bármikor változhat. A típusok a következők: auth_error, permission_error, invalid_request_error, not_found_error, rate_limit_error és api_error.

Egy 5xx esetén az üzenet szándékosan általános. Ehelyett idézd a request_id -t – ez szerepel a REST válaszokban mint a X-Request-Id fejléc, és ez alapján találjuk meg azt az egyetlen naplósort, amely releváns.

MCP tool hibák

Az MCP tool elutasítások – beleértve a kimerült budgeteket is – a következőt adják vissza: isError: true szöveges leírással a content mezőben, egy JSON-RPC HTTP 200 válaszon belül. Ezek nem használják a REST típusos hiba-borítékot, sem a rate-limit fejléceket. A tool eredményét vizsgáld, ne csak a HTTP státuszt. Használd a whoami a fiók- és scope-információkhoz; a budget hibák jelzik, mikor érdemes várni az újrapróbálkozás előtt.

Egy build véletlen kétszeri elindítása

Egy build, amely a te oldaladon time outol, könnyen elindulhatott a mi oldalunkon is, és a vak újrapróbálkozás egy második generálást is kifizet. Küldj el egy általad választott Idempotency-Key értéket:

POST /app/api/v3/runs
Idempotency-Key: build-2026-09-08-homepage-01

Az azonos kulccsal végzett újrapróbálkozás az első hívás run-ját adja vissza egy újabb elindítása helyett, és tartalmazza az Idempotent-Replay: true-t. A kulcsokat fiókonként 24 órán át vesszük figyelembe. Egy hibás formátumú kulcsot elutasítunk, nem pedig csendben ignorálunk – ha védelmet kértél, akkor annak csendes elmaradása rosszabb lenne, mint az elutasítás. MCP-n ugyanez az idempotencyKey argumentuma a build_popup.

Várakozás egy build-re

Inkább a watch_job -t használd egy polling ciklus helyett. Megvárja a job-ot, és közben progress notification-öket küld, majd visszaadja a végállapotot. Ha eléri az időkorlátot, ezt jelzi, és megadja az addigi státuszt, így újra meghívhatod.

Használd a get_job -t egyszeri státuszlekéréshez, vagy ha a kliens nem tud nyitva tartani egy kérést. A REST kliensek streamelhetik a progress-t a /app/api/v3/runs/{runId}/events.

Mindkettő elfogad egy jobId-t, és amit a runId build_popup ad neked, az pontosan ilyen – add tovább változatlanul. Ugyanezek a két tool várnak egy sorba állított design-thread változásra is, így egyetlen módja van annak, hogy megvárj bármit, amit ez az API elindít.

Egy dolgot mindenképp érdemes tudni: nézd a terminal-t, ne a státuszszót. Egy run, amely interrupted volt, folytatódik, és továbbra is futóként jelenti magát; ennek a szónak hibaként való kezelése volt a leggyakoribb hiba ezen a felületen, és a boolean pontosan azért van, hogy erre soha ne legyen szükséged.

Meglévő klienst migrálsz? watch_build és get_build_status eltávolításra kerültek. Helyettük használd a watch_job és get_job, a régi runId -t mint jobId-t átadva. A build hibák most a status: failed; sourceStatus -t jelentik, amely megőrzi az alapul szolgáló run státuszát. Egy selected job végállapotú a várakozás szempontjából, de nem épített le semmit: hívd meg a select_variant-t a design thread-ben, hogy elindítsd a build-jét.

Várakozás egy design thread-re

A design szakaszban ugyanez érhető el: watch_design_thread. Megvárja, amíg a threadnek szüksége lesz RÁD – az agent felfedező kérdést tesz fel, a concept card-ok és azok mockup-jai mind elkészültek, vagy a thread véget ér –, és azonnal visszatér, ha ezek közül már fennáll valamelyik. Egy félig kész board nem tartozik ezek közé, így nem ébresztünk fel minden egyes megérkező mockup miatt. Időtúllépés esetén ezt jelzi, és újra meghívhatod; soha ne alkalmazz sleep-et vagy pollingot get_design_thread a hívások között. A reason és next mezők mondják meg, hogy a négy eset közül melyik történt, és mit kell tenned ezzel kapcsolatban.

Rate limitek

A rate-limit middleware-en áthaladó REST válaszok tartalmazzák a X-RateLimit-Limit, X-RateLimit-Remaining -t és a X-RateLimit-Reset -t (epoch másodpercek). Egy REST budget elutasítás egy 429 -vel Retry-After. A fennmaradó keretet használd a kérések ütemezésére; párhuzamos hívások továbbra is kimeríthetik azt, ezért az elutasításokat is kezelned kell.

Géppel olvasható szerződés (kontraktus)

A REST felületet egy OpenAPI 3.1 dokumentum írja le, és van egy rövid pointer fájl is az agentek számára:

GET /.well-known/openapi.json
GET /llms.txt

Mindkettő hitelesítés nélkül olvasható, így egy kliens még azelőtt eldöntheti, hogy integrálódik-e, mielőtt bárki létrehozna egyet.