Hibák, lapozás és kvóták

Ezek a konvenciók a teljes REST API-ra vonatkoznak. Az MCP hibakezelése ettől eltér, erről itt olvashatsz: Az MCP áttekintése.

A hibaválasz törzse

Szinte minden hiba egy JSON-objektum, egyetlen, ember által olvasható üzenettel:

{"error": "Conversation not found"}

Általános, gépi feldolgozásra szánt hibakódok nincsenek. Néhány hibacsalád egy további mezőt is visszaad:

Az adatrezidencia-kódok: EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED és NO_ENDPOINT_AVAILABLE. Egyes hitelesítési hibák csak egy állapotkódot adnak vissza, üres törzzsel, ezért ne feltételezd, hogy minden hibaválasz JSON-ként értelmezhető.

Állapotkódok

Az egyes végpontok pontos állapotkódjait a REST-referencia oldalai sorolják fel. A hitelesítési hibákról az API-kulcsok és hitelesítés oldalon olvashatsz bővebben.

Kvóták

Azok a végpontok, amelyek kreditköteles munkát indítanak (futtatások, beszélgetések, médiagenerálás, hangátírás, tudásbázis-feltöltés és fájlfeldolgozás), először ellenőrzik a munkaterület csomagját és kreditjeit. Ha az ellenőrzés nem sikerül, ezt adják vissza:

HTTP 429
{"error": "Quota exceeded", "reason": "credit_count"}

Ez a 429 nem sebességkorlát, így az azonnali újrapróbálkozás nem segít. Juttasd el a hibát valakihez, aki intézkedni tud. A kreditekről és a csomagokról a Felhasználás, kreditek és számlázás oldalon olvashatsz.

Sebességkorlátozás

Nincs közzétett, kulcsonkénti vagy felhasználónkénti kérési sebességkorlát (rate limit). Az áteresztőképességet a munkaterület csomagja és kreditjei határozzák meg, a korlát elérését pedig a fenti 429 Quota exceeded válasz jelzi. A hosszú szinkron hívások (egy lassú modell, egy hosszú hangátírás) addig tartanak, amíg a munka elkészül, ezért állíts be bőséges időkorlátot a HTTP-kliensedben.

Lapozás

A lapozható listázó végpontok két lekérdezési paramétert fogadnak:

A lapozási adatok a válasz headereiben vannak, nem a törzsben. A törzs egy egyszerű JSON-tömb.

Egyes listázó végpontok mindent visszaadnak, ha nem küldesz lapozási paramétert (például a GET /ai_model). Hogy melyek ezek, azt az adott végpont referenciája jelzi.

curl -i "https://api.stickyprompts.com/api/v1/conversation?page=2&size=25" \
  -H "Authorization: Bearer $STICKY_API_KEY"
# X-Page: 2
# X-Page-Size: 25
# X-Total-Count: 137

import os
import requests

BASE = "https://api.stickyprompts.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

def all_conversations(size=50):
    page = 1
    while True:
        r = requests.get(f"{BASE}/conversation", headers=HEADERS,
                         params={"page": page, "size": size})
        r.raise_for_status()
        yield from r.json()
        if page * size >= int(r.headers["X-Total-Count"]):
            break
        page += 1

const BASE = "https://api.stickyprompts.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.STICKY_API_KEY}` };

async function* allConversations(size = 50) {
  for (let page = 1; ; page++) {
    const res = await fetch(`${BASE}/conversation?page=${page}&size=${size}`, { headers });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    yield* await res.json();
    if (page * size >= Number(res.headers.get("X-Total-Count"))) break;
  }
}

Az MCP-eszközök másként lapoznak: limit és offset argumentummal, az eredményben pedig egy total_count mezővel. Részletek: Eszközreferencia.

Azonosítók és mezőnevek

• A legtöbb erőforrás numerikus azonosítót használ. Sok végpont az azonosító helyett egy 8 karakteres slug értéket is elfogad; hogy hol, azt a referenciaoldalak jelzik.
• A legtöbb rekord négy alapmezőt tartalmaz, nagybetűvel kezdődő kulccsal: ID, CreatedAt, UpdatedAt és DeletedAt. A többi mező snake_case, néhány pedig camelCase (például az üzeneteknél az isUser, a beszélgetéseknél a userId és a projectId).
• Egyes egyedileg összeállított válaszok, például a promptfuttatások eredményei, helyettük kisbetűs id és created_at mezőt használnak.
• A tizedes típusú kredit- és pénzértékek (például credits_used, multiplier) JSON-stringként érkeznek, például "0.4213". Decimális típussal dolgozd fel őket, ne lebegőpontos számként.

{
  "ID": 5120,
  "CreatedAt": "2026-09-28T09:13:58Z",
  "DeletedAt": null,
  "slug": "aB3dE5gH",
  "userId": 77,
  "next_message_ai_model_id": 42,
  "credits_used": "0.4213"
}

A kliensedben egyenként, explicit módon képezd le a mezőket, ne egyetlen elnevezési konvencióra hagyatkozz.

Korrelációs azonosító

Minden válasz tartalmaz egy X-Correlation-ID headert. Rögzítsd a saját kérésnaplóidban is. Ha egy konkrét hívással kapcsolatban segítségre van szükséged, add meg ezt az azonosítót is, amikor a hello@stickyprompts.com címre írsz.

Földrajzi korlátozás

A rendszer elutasítja azokat a kéréseket, amelyek olyan régióból érkeznek, amelyet a szolgáltatás nem szolgál ki. Ez a REST-re és az MCP-re egyaránt vonatkozik:

HTTP 403
{"error": "access from your region is not supported"}

A felhasználás elszámolása

Az API- és MCP-hívások ugyanazon a végrehajtási, kvóta- és számlázási úton haladnak, mint a webalkalmazás műveletei. A felhasználást a rendszer a kulcs tulajdonosához és az ő munkaterületéhez rendeli, pontosan úgy, mintha ugyanezt az alkalmazásban tette volna, és ugyanazokból a kreditekből vonja le. Nincs külön API-árlista, és az API-felhasználás nem jelenik meg külön az alkalmazásbeli felhasználástól. Az egyes futtatások válaszai nem tartalmaznak tokenszámot vagy költséget; a munkaterület adminisztrátorai a felhasználást a Felhasználás, kreditek és számlázás oldalon leírt módon követhetik.