Errori, paginazione e quote

Queste convenzioni valgono per tutta l’API REST. MCP gestisce gli errori a modo suo, come spiegato in Panoramica di MCP.

Il corpo degli errori

Quasi ogni errore è un oggetto JSON con un unico messaggio leggibile da una persona:

{"error": "Conversation not found"}

Non esistono codici di errore generali leggibili da una macchina. Alcune famiglie di errori aggiungono un campo in più:

I codici relativi alla residenza dei dati sono EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED e NO_ENDPOINT_AVAILABLE. Alcuni errori di autenticazione restituiscono solo lo stato, con il corpo vuoto, quindi non dare per scontato che ogni risposta di errore sia un JSON valido.

Codici di stato

Gli stati esatti di ogni endpoint sono elencati nelle singole pagine di riferimento REST. Gli errori di autenticazione sono spiegati in Chiavi API e autenticazione.

Quote

Le route che avviano lavoro a pagamento - esecuzioni, conversazioni, generazione di media, trascrizione, caricamenti nelle knowledge base ed elaborazione di file - verificano prima il piano e i crediti del workspace. Se la verifica non va a buon fine, restituiscono:

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

In questo caso un 429 non è un rate limit, quindi riprovare subito non serve. Segnalalo a una persona che possa intervenire. Crediti e piani sono trattati in Utilizzo, crediti e fatturazione.

Rate limit

Non esiste un rate limit pubblicato per chiave o per utente. Il volume di richieste dipende dal piano e dai crediti del tuo workspace, e i limiti si manifestano con la risposta 429 Quota exceeded descritta sopra. Le chiamate sincrone lunghe (un modello lento, una trascrizione estesa) durano quanto il lavoro che svolgono, quindi imposta un timeout generoso nel tuo client HTTP.

Paginazione

Gli endpoint di elenco che paginano accettano due parametri di query:

I metadati di paginazione si trovano negli header della risposta, non nel corpo. Il corpo è un semplice array JSON.

Alcuni endpoint di elenco restituiscono tutto quando non invii parametri di paginazione (per esempio GET /ai_model). Il riferimento di ogni endpoint indica quali.

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

Gli strumenti MCP paginano in modo diverso, con gli argomenti limit e offset e un total_count nel risultato. Consulta Riferimento degli strumenti.

ID e convenzioni dei nomi dei campi

• La maggior parte delle risorse usa ID numerici. Molti endpoint accettano anche uno slug di 8 caratteri al posto dell’ID; le pagine di riferimento indicano dove.
• La maggior parte dei record include quattro campi di base con chiavi con l’iniziale maiuscola: ID, CreatedAt, UpdatedAt e DeletedAt. Gli altri campi sono in snake_case, e alcuni in camelCase (per esempio isUser nei messaggi, userId e projectId nelle conversazioni).
• Alcune risposte costruite a mano, come i risultati delle esecuzioni dei prompt, usano invece id e created_at in minuscolo.
• I valori di crediti e importi tipizzati come decimali (per esempio credits_used, multiplier) arrivano come stringhe JSON, del tipo "0.4213". Interpretali con un tipo decimale, non con un float.

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

Nel tuo client mappa i campi in modo esplicito, invece di affidarti a un’unica convenzione di denominazione.

Correlation ID

Ogni risposta contiene un header X-Correlation-ID. Registralo insieme ai log delle tue richieste. Se ti serve aiuto su una chiamata specifica, includilo quando scrivi a hello@stickyprompts.com.

Restrizione geografica

Le richieste provenienti da una regione non servita vengono rifiutate, sia via REST sia via MCP:

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

Come viene conteggiato l’utilizzo

Le chiamate API e MCP seguono lo stesso percorso di esecuzione, quote e fatturazione della web app. L’utilizzo viene attribuito al proprietario della chiave e al suo workspace, esattamente come se avesse fatto la stessa cosa nell’app, e attinge agli stessi crediti. Non esiste un listino prezzi separato per l’API, e l’utilizzo dell’API non viene riportato separatamente da quello dell’app. Le singole risposte delle esecuzioni non includono il numero di token né il costo; gli amministratori del workspace vedono l’utilizzo in Utilizzo, crediti e fatturazione.