Errores, paginación y cuotas

Estas convenciones se aplican a toda la API REST. MCP tiene su propio comportamiento ante los errores, que se explica en Introducción a MCP.

El cuerpo de error

Casi todos los errores son un objeto JSON con un único mensaje legible por personas:

{"error": "Conversation not found"}

No hay códigos de error generales pensados para máquinas. Algunas familias de errores añaden un campo adicional:

Los códigos de residencia de datos son EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED y NO_ENDPOINT_AVAILABLE. Algunos fallos de autenticación devuelven solo el código de estado, con el cuerpo vacío, así que no des por hecho que todas las respuestas de error se pueden analizar como JSON.

Códigos de estado

Los códigos de estado exactos de cada endpoint aparecen en cada página de referencia REST. Los errores de autenticación se explican en Claves de API y autenticación.

Cuotas

Las rutas que inician trabajo de pago (ejecuciones, conversaciones, generación multimedia, transcripción, subidas a bases de conocimiento y procesamiento de archivos) comprueban primero el plan y los créditos del espacio de trabajo. Si la comprobación falla, devuelven:

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

En este caso, un 429 no es un límite de frecuencia, así que reintentar de inmediato no servirá de nada. Hazlo llegar a una persona que pueda resolverlo. Los créditos y los planes se explican en Uso, créditos y facturación.

Límites de frecuencia

No hay ningún límite publicado de peticiones por clave ni por usuario. El volumen de trabajo lo determinan el plan y los créditos de tu espacio de trabajo, y se comunica mediante la respuesta 429 Quota exceeded descrita arriba. Las llamadas síncronas largas (un modelo lento, una transcripción larga) duran lo que tarde el trabajo, así que configura un tiempo de espera generoso en tu cliente HTTP.

Paginación

Los endpoints de listas que paginan aceptan dos parámetros de consulta:

Los metadatos de paginación van en los headers de la respuesta, no en el cuerpo. El cuerpo es un array JSON simple.

Algunos endpoints de listas lo devuelven todo si no envías parámetros de paginación (por ejemplo, GET /ai_model). La referencia de cada endpoint indica cuáles.

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

Las herramientas MCP paginan de otra forma: con los argumentos limit y offset, y con un total_count en el resultado. Consulta la referencia de herramientas MCP.

ID y mayúsculas en los nombres de campo

• La mayoría de los recursos usan ID numéricos. Muchos endpoints aceptan también un slug de 8 caracteres en lugar del ID; las páginas de referencia indican dónde.
• La mayoría de los registros incluyen cuatro campos base cuyas claves van con mayúscula inicial: ID, CreatedAt, UpdatedAt y DeletedAt. El resto de los campos están en snake_case, y algunos en camelCase (por ejemplo, isUser en los mensajes, o userId y projectId en las conversaciones).
• Algunas respuestas construidas a mano, como los resultados de ejecución de prompts, usan en su lugar id y created_at en minúsculas.
• Los valores de créditos e importes de tipo decimal (por ejemplo, credits_used o multiplier) llegan como cadenas JSON, del tipo "0.4213". Analízalos con un tipo decimal, no con uno de coma flotante.

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

En tu cliente, asigna cada campo de forma explícita en lugar de depender de una única convención de nombres.

ID de correlación

Cada respuesta incluye un header X-Correlation-ID. Regístralo junto con tus propios logs de peticiones. Si necesitas ayuda con una llamada concreta, inclúyelo cuando escribas a hello@stickyprompts.com.

Restricción geográfica

Las peticiones procedentes de una región en la que el servicio no está disponible se rechazan, tanto en REST como en MCP:

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

Cómo se cuenta el uso

Las llamadas a la API y a MCP pasan por la misma ruta de ejecución, cuotas y facturación que la aplicación web. El uso se atribuye al propietario de la clave y a su espacio de trabajo, exactamente igual que si hubiera hecho lo mismo en la aplicación, y consume los mismos créditos. No hay una lista de precios aparte para la API, y el uso de la API no se muestra por separado del uso de la aplicación. Las respuestas de cada ejecución no incluyen el recuento de tokens ni el coste; los administradores del espacio de trabajo ven el uso en Uso, créditos y facturación.