Fehler, Paginierung und Kontingente

Diese Konventionen gelten für die gesamte REST-API. MCP verhält sich bei Fehlern anders. Das ist unter MCP im Überblick beschrieben.

Der Fehler-Body

Fast jeder Fehler ist ein JSON-Objekt mit einer einzigen, für Menschen lesbaren Meldung:

{"error": "Conversation not found"}

Allgemeine maschinenlesbare Fehlercodes gibt es nicht. Einige Fehlerarten bringen ein zusätzliches Feld mit:

Die Codes für die Datenresidenz lauten EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED und NO_ENDPOINT_AVAILABLE. Manche Authentifizierungsfehler liefern nur einen Status mit leerem Body. Gehen Sie also nicht davon aus, dass sich jede Fehlerantwort als JSON parsen lässt.

Statuscodes

Die genauen Statuscodes pro Endpunkt stehen auf der jeweiligen Seite der REST-Referenz. Die Authentifizierungsfehler sind unter API-Schlüssel und Authentifizierung erklärt.

Kontingente

Routen, die kostenpflichtige Arbeit starten, prüfen zuerst den Tarif und die Credits des Workspace. Dazu gehören Ausführungen, Unterhaltungen, Mediengenerierung, Transkription, Uploads in Wissensdatenbanken und die Dateiverarbeitung. Schlägt die Prüfung fehl, antworten sie mit:

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

Ein 429 ist hier keine Ratenbegrenzung, ein sofortiger neuer Versuch hilft also nicht. Leiten Sie die Meldung an eine Person weiter, die etwas unternehmen kann. Credits und Tarife werden unter Nutzung, Credits und Abrechnung erklärt.

Ratenbegrenzungen

Es gibt keine veröffentlichte Ratenbegrenzung pro Schlüssel oder pro Benutzer. Der Durchsatz richtet sich nach dem Tarif und den Credits Ihres Workspace und wird über die oben beschriebene Antwort 429 Quota exceeded gemeldet. Lange synchrone Aufrufe (ein langsames Modell, eine lange Transkription) dauern so lange wie die Arbeit selbst. Geben Sie Ihrem HTTP-Client daher ein großzügiges Timeout.

Paginierung

Listen-Endpunkte mit Paginierung nehmen zwei Query-Parameter entgegen:

Die Metadaten zur Seite stehen in den Response-Headern, nicht im Body. Der Body ist ein einfaches JSON-Array.

Manche Listen-Endpunkte liefern alles zurück, wenn Sie keine Paginierungsparameter senden (zum Beispiel GET /ai_model). Welche das sind, steht in der Referenz des jeweiligen Endpunkts.

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;
  }
}

MCP-Tools paginieren anders, mit den Argumenten limit und offset und einem total_count im Ergebnis. Siehe Tool-Referenz.

IDs und Schreibweise der Felder

• Die meisten Ressourcen verwenden numerische IDs. Viele Endpunkte akzeptieren statt der ID auch einen 8-stelligen slug. Wo das geht, steht auf den Referenzseiten.
• Die meisten Datensätze enthalten vier Basisfelder mit großgeschriebenen Schlüsseln: ID, CreatedAt, UpdatedAt und DeletedAt. Die übrigen Felder sind in snake_case geschrieben, einige wenige in camelCase (zum Beispiel isUser bei Nachrichten, userId und projectId bei Unterhaltungen).
• Einige von Hand geschriebene Antworten, etwa Ergebnisse von Prompt-Ausführungen, verwenden stattdessen kleingeschriebenes id und created_at.
• Credit- und Geldbeträge, die als Dezimalzahlen typisiert sind (zum Beispiel credits_used, multiplier), kommen als JSON-Strings wie "0.4213" an. Parsen Sie sie mit einem Dezimaltyp, nicht als Gleitkommazahl.

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

Ordnen Sie die Felder in Ihrem Client explizit zu, statt sich auf eine einzige Namenskonvention zu verlassen.

Korrelations-ID

Jede Antwort enthält einen Header X-Correlation-ID. Protokollieren Sie ihn zusammen mit Ihren eigenen Request-Logs. Wenn Sie Hilfe zu einem bestimmten Aufruf brauchen, geben Sie ihn an, wenn Sie an hello@stickyprompts.com schreiben.

Geografische Einschränkung

Requests aus einer Region, die der Dienst nicht bedient, werden abgelehnt, bei REST wie bei MCP:

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

So wird die Nutzung gezählt

API- und MCP-Aufrufe laufen über dieselbe Ausführung, dieselben Kontingente und dieselbe Abrechnung wie die Web-App. Die Nutzung wird dem Inhaber des Schlüssels und seinem Workspace zugerechnet, genau so, als hätte er dasselbe in der App getan, und verbraucht dieselben Credits. Es gibt keine eigene API-Preisliste, und die API-Nutzung wird nicht getrennt von der App-Nutzung ausgewiesen. Einzelne Antworten von Ausführungen enthalten weder Token-Zahlen noch Kosten. Workspace-Admins sehen die Nutzung unter Nutzung, Credits und Abrechnung.