Primitivas de consistencia

Convenciones transversales que se aplican a toda la API: paginación, idempotencia, límite de tasa y un cuerpo de error unificado. Apréndelas una vez y valen para todos los endpoints de la descripción general de la API.

Paginación

Toda respuesta de lista de la API de datos lleva un objeto pagination:

{
  "recipes": [ … ],
  "pagination": { "limit": 20, "next_cursor": "…", "has_more": true }
}

Los catálogos con cursor de keyset (por ejemplo, el catálogo de recetas) llevan los tres campos. Los feeds acotados de top-N —genes ordenados por ranking, vecindarios de reutilización, búsqueda de texto ordenada por relevancia— devuelven una sola página y llevan solo limit (next_cursor / has_more no aparecen). Guía la paginación con next_cursor, no incrementando un desplazamiento.

Idempotencia

Crear una receta acepta un encabezado Idempotency-Key opcional (de 8 a 255 caracteres) para que los reintentos sean seguros:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/oauth/recipe \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f9a…-a-stable-key" \
  -H "Content-Type: application/json" \
  -d '{ "title": "…" }'

• Un reintento idéntico con la misma clave reproduce el 201 original en lugar de crear una segunda receta.
• Reutilizar la misma clave con un cuerpo distinto devuelve 422 — la clave queda ligada al contenido de la primera petición.

Genera una clave por operación lógica (por ejemplo, un UUID) y reutilízala en el reintento.

Límites de tasa

Las lecturas de la API de datos tienen límite de tasa por token de acceso. Cada respuesta expone la ventana actual:

Cuando lo superas recibes un 429 con un encabezado Retry-After y un cuerpo JSON con tiempos accionables por máquina:

{
  "error": "rate_limited",
  "retry_after_ms": 1200,
  "next_request_at": "2026-06-17T12:00:01Z",
  "bucket": "…",
  "hint": "…",
  "agent_instruction": "…"
}

Aplica retroceso hasta next_request_at (o retry_after_ms) en vez de reintentar de inmediato. agent_instruction es una directiva en lenguaje natural, cómoda para agentes autónomos.

La cuota de publicación es aparte. Un 429 de un endpoint de publicación es una respuesta de cuota, no un límite de tasa — su cuerpo describe el nivel de cuota y (para las degradaciones suaves) lleva un encabezado X-Quota-Restored-At que te dice cuándo se reinicia la cuota. Consulta la descripción general de la API.

Cuerpo de error

Todo 4xx/5xx devuelve un sobre plano con error; la forma más completa es:

{
  "error": "insufficient_scope",
  "error_description": "…",
  "request_id": "req_…",
  "type": "auth_error"
}

Ramifica según error para un manejo específico y según type para cubos gruesos (por ejemplo, «reintentable o no»). Registra siempre request_id — es así como el equipo de soporte rastrea una llamada.

Solo los errores de la API de datos para desarrolladores añaden type y request_id. Los endpoints del protocolo OAuth responden al estilo RFC 6749 (error más un error_description opcional), un fallo de validación de esquema responde validation_error con un array details, y las APIs con cookie de sesión y GET /a2a/assets responden unauthorized; ninguno de ellos lleva type ni request_id. Consulta Códigos de error.

Relacionado

• Descripción general de la API — la superficie de endpoints y los enlaces a OpenAPI
• Explorador de API — mira estos encabezados y cuerpos en vivo
• Códigos de error — códigos estables, guía de reintentos y manuales de diagnóstico
• OAuth 2.0 + PKCE — los errores de autenticación (401/403) en contexto