# Hibák és korlátok

> Hibaformátum, kódok, sebességkorlát, méretkorlátok.

## A hibák formátuma

Minden hibaválasz ugyanilyen JSON:

```json
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"email":"Enter a valid email address."}}}
```

| Kulcs | Jelentés |
|---|---|
| `code` | Állandó, gépi feldolgozásra szánt kód. Erre építsd az elágazásokat. |
| `message` | Emberi olvasásra szánt szöveg az `Accept-Language` nyelvén (`en` vagy `hu`). Változhat, ne dolgozd fel. |
| `fields` | Csak a kérés tartalmát érintő hibáknál: a probléma kulcsonként, emberi olvasásra szánt szövegként. A beágyazott kulcsokat pont választja el (`fields.rendelesek_szama`, `content.html`, `requests.0`). |

Ugyanez a kérés `Accept-Language: hu` fejléccel:

```json
{"error":{"code":"validation","message":"Ellenőrizd a megjelölt mezőket.","fields":{"email":"Adj meg érvényes e-mail-címet."}}}
```

Ha az útvonal nem fogadja a metódust, a válasz `405`, az `Allow` fejléccel:

```bash
curl -i -X PATCH "$ECHO_API/groups" -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" -d '{"name":"x"}'
```

```http
HTTP/1.1 405 Method Not Allowed
Allow: OPTIONS, GET, POST
Content-Type: application/json

{"error":{"code":"method_not_allowed","message":"This method is not allowed here."}}
```

Ha a törzs nem érvényes JSON, vagy nem egyetlen JSON-objektum, a válasz `400`:

```bash
curl -X POST "$ECHO_API/groups" -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" -d '{"name":'
```

```json
{"error":{"code":"invalid_json","message":"The request body is not a valid JSON object."}}
```

A rossz típusú érték `422 validation` hibát ad, a kulccsal a `fields` alatt: például a `{"name":5}` törzsre `"fields":{"name":"Invalid value."}`.

## HTTP-állapotkódok

| Kód | Jelentés |
|---|---|
| `200`, `201`, `202`, `204` | Kész; létrehozva; háttérmunkára elfogadva; kész, törzs nélkül. |
| `400` | A törzs nem érvényes JSON, vagy nem egyetlen JSON-objektum (`invalid_json`). |
| `401` | Nincs érvényes token (`unauthenticated`). |
| `403` | A token ezt nem teheti meg (`forbidden`), vagy a cím, a munkaterület vagy a kétlépcsős szabály akadályozza. |
| `404` | Ismeretlen azonosító vagy útvonal (`not_found`). |
| `405` | Az útvonal létezik, de nem ezzel a metódussal (`method_not_allowed`). Az `Allow` fejléc felsorolja, mit fogad. |
| `409` | A kérés ütközik a jelenlegi állapottal (lásd a kódokat lent). |
| `413` | Túl nagy a törzs (`too_large`). |
| `415` | A törzs nem `application/json` (`unsupported_media_type`). |
| `422` | A tartalmat az API megértette, de elutasította (`validation` és a lenti kódok). |
| `429` | Elfogyott a sebességkeret (`rate_limited`). |
| `503` | Egy lista vagy számolás túl sokáig tartott (`list_timeout`). Szűkítsd a szűrést, és próbáld újra. |

## Hibakódok

| Kód | Állapot | Mikor |
|---|---|---|
| `unauthenticated` | 401 | A token hiányzik, ismeretlen vagy visszavont, vagy a létrehozója kikerült a munkaterületről vagy le van tiltva. |
| `ip_not_allowed` | 403 | A token más IP-címekre van korlátozva. |
| `workspace_suspended` | 403 | A munkaterület fel van függesztve. |
| `twofa_enforced` | 403 | A munkaterület kétlépcsős azonosítást követel, és a token létrehozója nem állította be. Amint beállítja, a token újra működik. |
| `forbidden` | 403 | A token hozzáférési szintje vagy a létrehozója szerepköre ezt nem engedi. |
| `not_found` | 404 | Az azonosító nem létezik ebben a munkaterületben, vagy ismeretlen az útvonal. |
| `method_not_allowed` | 405 | Az útvonal nem fogadja ezt a metódust; lásd az `Allow` fejlécet. |
| `invalid_json` | 400 | A törzs nem érvényes JSON, vagy nem egyetlen JSON-objektum. |
| `validation` | 422 | Hibás a kérés tartalma; lásd `fields`. |
| `unsupported_media_type` | 415 | Küldd a `Content-Type: application/json` fejlécet. |
| `too_large` | 413 | 1 MB fölött (importnál 10 MB fölött). |
| `rate_limited` | 429 | Lásd [Sebességkorlát](#sebességkorlát). |
| `name_taken` | 409 | Már van ilyen nevű csoport vagy mező. |
| `in_use` | 409 | A törlendő csoportot vagy szegmenst szegmens, kampány vagy munkafolyamat használja; az üzenet megnevezi őket. |
| `builtin_field` | 409 | Beépített mező nem nevezhető át és nem törölhető. |
| `webhook_limit` | 409 | A munkaterületnek 20 webhookja van. |
| `unknown_tags` | 422 | A kampány tartalmában nem létező címkék vannak. |
| `not_editable` | 409 | A kampány olyan állapotban van, amely ezt nem engedi (nem piszkozat, még küldés alatt áll, vagy más szerkesztő tartalma). |
| `editor_chosen` | 409 | Egy párhuzamos kérés más szerkesztőt választott a piszkozathoz. |
| `recently_sent` | 409 | A 30 napon belül kiküldött kampány még nem törölhető. |
| `not_active` | 409 | A munkafolyamat piszkozat (szüneteltetés), vagy nem aktív (feliratkozók hozzáadása). |
| `list_timeout` | 503 | A lista túl sokáig tartott. |

Az ismeretlen kódokat a HTTP-állapotuk szerint kezeld: új kódok is bekerülhetnek.

## Sebességkorlát

| Keret | Korlát | Mi számít bele |
|---|---|---|
| Általános | Tokenenként percenként 120 kérés | Minden hitelesített kérés, a kötegek és a kötegekben lévő kérések is. |
| Import | Tokenenként percenként 5 | A `POST /groups/{id}/import-subscribers`, amely az általános keretbe is beleszámít. |

A korlát naptári percre (minden perc elején újraindul) és tokenre érvényes. A beszámító válaszok fejlécei:

| Fejléc | Jelentés |
|---|---|
| `X-RateLimit-Limit` | A keret korlátja. Import válaszában az importkeretet mutatja. |
| `X-RateLimit-Remaining` | Ebben a percben még hátralévő kérések. |
| `Retry-After` | Csak `429` esetén: másodpercek a következő percig. |

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 18
X-Ratelimit-Limit: 120
X-Ratelimit-Remaining: 0

{"error":{"code":"rate_limited","message":"Too many requests with this API token. Wait a minute and try again, or send several requests in one batch."}}
```

A be nem számító válaszokban nincsenek sebességkorlát-fejlécek: ilyen a sikertelen hitelesítés, az elutasított IP-címről érkező kérés és a `GET /openapi.yaml`.

Jó gyakorlat: figyeld az `X-RateLimit-Remaining` értékét, `429` után várj `Retry-After` másodpercet, sok változtatáshoz használj [kötegelt kéréseket](https://docs.uptools.io/hu/echo/developer-guide/batch-requests/) és a tömeges importot, és külön rendszerekhez külön tokent adj (minden tokennek saját kerete van).

## További korlátok

| Mi | Korlát |
|---|---|
| A kérés törzse | 1 MB; tömeges importnál 10 MB |
| Oldalméret (`limit`) | 1-100, alapból 25 |
| Feliratkozói tevékenység oldala | 50 esemény |
| Tömeges import | Kérésenként 1-50 000 sor |
| Köteg | 1-50 kérés |
| Feliratkozók munkafolyamathoz adása | Kérésenként 1-100 |
| Tesztlevél | Kérésenként 1-5 cím; munkaterületenként bármely 24 órában 50 |
| Webhookok | Munkaterületenként 20; kötegelt kézbesítésenként legfeljebb 100 esemény; 10 másodperc a válaszra |
| API-tokenek | Munkaterületenként 50 aktív; tokenenként 20 IP-cím vagy tartomány |
| Nevek | Webhook- és tokennév legfeljebb 100, kampánynév és tárgy legfeljebb 255 karakter |