Erreurs, pagination et quotas

Ces conventions valent pour toute l’API REST. MCP gère les erreurs à sa façon, comme l’explique la Vue d’ensemble de MCP.

Le corps des erreurs

Presque toutes les erreurs sont un objet JSON contenant un seul message lisible par un humain :

{"error": "Conversation not found"}

Il n’existe pas de codes d’erreur généraux destinés aux machines. Quelques familles d’erreurs ajoutent un champ supplémentaire :

Les codes de résidence des données sont EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED et NO_ENDPOINT_AVAILABLE. Certains échecs d’authentification renvoient un simple statut avec un corps vide : ne partez donc pas du principe que toute réponse d’erreur peut être analysée comme du JSON.

Codes de statut

Les statuts exacts de chaque endpoint sont indiqués sur la page de référence REST correspondante. Les erreurs d’authentification sont détaillées dans Clés API et authentification.

Quotas

Les routes qui lancent un travail payant (exécutions, conversations, génération de médias, transcription, téléversements dans les bases de connaissances et traitement de fichiers) vérifient d’abord le plan et les crédits de l’espace de travail. Si la vérification échoue, elles renvoient :

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

Ici, un 429 n’est pas une limite de débit : réessayer immédiatement ne servira à rien. Signalez-le à une personne qui peut agir. Les crédits et les plans sont présentés dans Utilisation, crédits et facturation.

Limites de débit

Aucune limite de débit par clé ou par utilisateur n’est publiée. Le volume traité dépend du plan et des crédits de votre espace de travail, signalés par la réponse 429 Quota exceeded décrite ci-dessus. Les appels synchrones longs (un modèle lent, une longue transcription) durent le temps du travail à effectuer : prévoyez un délai d’expiration généreux dans votre client HTTP.

Pagination

Les endpoints de liste paginés acceptent deux paramètres de requête :

Les métadonnées de pagination se trouvent dans les headers de la réponse, pas dans le corps. Le corps est un simple tableau JSON.

Certains endpoints de liste renvoient tout lorsque vous n’envoyez aucun paramètre de pagination (par exemple GET /ai_model). La référence de chaque endpoint précise lesquels.

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

Les outils MCP paginent différemment, avec les arguments limit et offset et un total_count dans le résultat. Voir la Référence des outils.

Identifiants et casse des champs

• La plupart des ressources utilisent des identifiants numériques. De nombreux endpoints acceptent aussi un slug de 8 caractères à la place de l’identifiant ; les pages de référence indiquent lesquels.
• La plupart des enregistrements comportent quatre champs de base dont les clés commencent par une majuscule : ID, CreatedAt, UpdatedAt et DeletedAt. Les autres champs sont en snake_case, et quelques-uns en camelCase (par exemple isUser sur les messages, userId et projectId sur les conversations).
• Certaines réponses construites à la main, comme les résultats d’exécution de prompts, utilisent à la place id et created_at en minuscules.
• Les valeurs de crédits et les montants typés en décimal (par exemple credits_used, multiplier) arrivent sous forme de chaînes JSON, comme "0.4213". Analysez-les avec un type décimal, pas avec un flottant.

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

Dans votre client, mappez les champs explicitement plutôt que de vous fier à une seule convention de nommage.

Identifiant de corrélation

Chaque réponse comporte un header X-Correlation-ID. Enregistrez-le avec vos propres logs de requêtes. Si vous avez besoin d’aide sur un appel précis, indiquez-le dans votre message à hello@stickyprompts.com.

Restriction géographique

Les requêtes provenant d’une région que le service ne dessert pas sont refusées, en REST comme en MCP :

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

Décompte de l’utilisation

Les appels API et MCP passent par le même circuit d’exécution, de quotas et de facturation que l’application web. L’utilisation est attribuée au propriétaire de la clé et à son espace de travail, exactement comme s’il avait effectué la même opération dans l’application, et consomme les mêmes crédits. Il n’existe pas de grille tarifaire distincte pour l’API, et l’utilisation de l’API n’est pas présentée séparément de celle de l’application. Les réponses d’exécution n’indiquent ni le nombre de tokens ni le coût ; les administrateurs de l’espace de travail consultent l’utilisation dans Utilisation, crédits et facturation.