- Documentación
- API · Versión 1.0
- Límites y convenciones
Límites y convenciones
En esta página
Lo que la API limita, y las convenciones que sigue en todas sus rutas: frecuencia, paginación, identificadores, fechas y cuotas.
Límites de frecuencia
Dos límites, que no miden lo mismo:
| Límite | Por defecto | Cuenta |
|---|---|---|
| Por dirección IP | 300 peticiones por minuto | Todas las peticiones, incluidas las que fallan en la autenticación. |
| Por cliente de API | 120 peticiones por minuto | Las peticiones autenticadas de este cliente, sea cual sea la dirección desde la que salen. |
El primero protege de un barrido de identificadores, que no pertenece a ningún cliente; el segundo, de una integración que se desboca.
Una respuesta autenticada lleva las cabeceras del límite del cliente:
| Cabecera | Significado |
|---|---|
X-RateLimit-Limit |
El número de peticiones permitidas por minuto. |
X-RateLimit-Remaining |
Las que quedan en el minuto en curso. |
Por encima de uno u otro, la API responde 429:
{
"error": {
"code": "too_many_requests",
"message": "Too many requests. Retry after the delay given by the Retry-After header."
}
}
La respuesta lleva entonces Retry-After (en segundos), X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (marca de tiempo Unix de la puesta a cero) del límite alcanzado. Espera el plazo de Retry-After antes de continuar, y vigila X-RateLimit-Remaining en las respuestas correctas para ir más despacio antes de que te detengan. Una petición rechazada por el límite del cliente no se cuenta en el consumo del espacio.
La notificación de control de un webhook tiene su propio límite: 5 por minuto y por endpoint (consulta Webhooks).
Paginación
GET /destinations, GET /publications y GET /media están paginadas. per_page vale 25 por defecto y está acotado entre 1 y 100. GET /brands y GET /webhooks devuelven la lista completa.
Las tres listas paginadas aceptan también brand_id: un cliente que cubre todo el espacio de trabajo lee en ellas una sola marca. Una marca fuera del alcance del cliente devuelve una lista vacía, sin error.
Una respuesta paginada lleva tres claves: data, links y meta.
{
"data": ["…"],
"links": {
"first": "https://quietsocial.dev/api/v1/publications?page=1",
"last": "https://quietsocial.dev/api/v1/publications?page=3",
"prev": null,
"next": "https://quietsocial.dev/api/v1/publications?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"links": ["…"],
"path": "https://quietsocial.dev/api/v1/publications",
"per_page": 25,
"to": 25,
"total": 61
}
}
Pagina siguiendo links.next hasta que valga null. Los parámetros de la petición — filtros incluidos — se conservan en esos enlaces. meta.links sirve para mostrar una paginación; sus etiquetas no forman parte del contrato.
Identificadores
La API nunca expone un número secuencial: se podría adivinar, y permitiría sondear los recursos de otro espacio. Cada recurso lleva un identificador público, con prefijo e inmutable:
| Prefijo | Recurso |
|---|---|
qsc_ |
Cliente de API |
brd_ |
Marca |
dst_ |
Destino |
pub_ |
Publicación |
med_ |
Medio |
whe_ |
Endpoint de webhook |
whd_ |
Entrega de webhook |
Tras el prefijo viene una secuencia de caracteres en minúsculas (pub_01k4b8y5t2v9h6p8w0y2z4b6c8). Trata el identificador como una cadena opaca, y no deduzcas nada de él.
Fechas y zonas horarias
Las fechas devueltas están en ISO 8601 con su desfase, en UTC. Las fechas enviadas deben seguir ISO 8601 y pueden llevar cualquier desfase: 2026-10-02T08:00:00+02:00 y 2026-10-02T06:00:00Z designan el mismo instante. Sin desfase, la hora se lee en UTC; cualquier otra forma se rechaza con 422.
timezone (zona horaria IANA, Europe/Paris) acompaña a una publicación; por defecto es la de la marca.
Cuotas
Una marca puede tener dos topes mensuales, legibles en GET /brands:
monthly_publication_limit— publicaciones creadas en el mes. Por encima, la creación responde422 publication_not_publishable.monthly_delivery_limit— entregas con éxito en una red en el mes. Se comprueba cuando una publicación retenida se libera conpublish:409 transition_not_allowedsi los objetivos que liberar superan lo que queda.
null significa «sin tope». Los contadores vuelven a cero el día 1 de cada mes, a medianoche UTC.
Lo que la API no hace
- No crea conexiones, destinos ni marcas: eso se hace en el panel.
- No valida una publicación sometida a validación; solo el equipo lo hace, en el panel.
- No devuelve direcciones de descarga de los medios.