Referencia

Límites y errores

Límites de peticiones#

Los límites se cuentan por dirección IP y por ventana de 60 segundos. Cada respuesta lleva cabeceras con tu situación:

Cabecera	Significado
`x-ratelimit-limit`	Peticiones permitidas en la ventana.
`x-ratelimit-remaining`	Las que te quedan.
`x-ratelimit-reset`	Segundos hasta que se reinicia.
`retry-after`	Con un `429`: segundos que debes esperar.

Rutas	Límite
API de disponibilidad (`/api/book/…`)	20 por minuto
OAuth, MCP y el resto de `/api/`	600 por minuto. Algunas acciones sensibles tienen límites propios más bajos.

Si te pasas, recibes 429. Espera lo que indique retry-after y reintenta con espera creciente. Guarda en caché lo que cambia poco: servicios y horario se pueden cachear unos minutos.

Formato de los errores#

Las rutas de Citeri responden con un objeto JSON con un mensaje en español, pensado para poder enseñárselo a una persona:

JSON

{ "error": "Negocio no encontrado" }

Con un 429, el objeto incluye además retryAfter.

OAuth sigue el formato del estándar (error y error_description), y el MCP el de JSON-RPC 2.0.

Códigos HTTP#

Código	Significado
`200`	Correcto.
`400`	Faltan parámetros o no son válidos (por ejemplo, `slots` sin `service_id` o `date`).
`401`	Falta el token o no es válido.
`402`	El negocio no tiene una suscripción activa: sus integraciones quedan en pausa.
`403`	El token no tiene permiso sobre ese recurso.
`404`	No existe, o el negocio no tiene la reserva pública activada.
`429`	Demasiadas peticiones.
`5xx`	Error nuestro. Reintenta con espera; si persiste, avísanos.

Versiones#

Las rutas documentadas no cambian de forma incompatible sin aviso previo en el changelog.
Podemos añadir campos nuevos en cualquier momento: tu código debe ignorar los que no conozca.
El MCP negocia la versión del protocolo con el cliente (2025-11-25, 2025-06-18 y 2025-03-26).

Estado del servicio#

Si algo no responde, escríbenos a info@citeri.es con la hora, la ruta y la respuesta que recibiste. Nunca nos mandes tokens ni claves.