Hibák és korlátok

A hibák formátuma

Minden hibaválasz ugyanilyen 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:

{"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:

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

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:

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

{"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.
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/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 é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