# Hibák, újrapróbálkozások és korlátok

Canonical URL: https://support.optimonk.com/hu/articles/errors-retries-and-limits

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.