Saltar a contenido

🚦 Límite de peticiones

La API pública limita cuántas peticiones puede hacer cada workspace en un periodo de tiempo, la ventana. Cada respuesta indica cuántas peticiones quedan y cuándo se restablece la cuota, así que tu integración puede ajustar su ritmo antes de llegar al límite.

Cómo se cuentan las peticiones

  • Cada workspace tiene una cuota de peticiones por ventana. El límite depende del workspace: consúltalo en la cabecera RateLimit-Limit de cualquier respuesta.
  • La cuota es compartida por todas las credenciales del workspace: las claves API, la CLI de Zinkee y el agente de Zinkee consumen de la misma cuota.
  • La ventana empieza con la primera petición. Cuando termina, la cuota se restablece por completo.
  • Las peticiones que la API rechaza por el límite, con el código 429, no consumen cuota. La excepción es un lote que no cabe en lo que queda: cuenta 1, como cualquier petición, aunque se rechace.

Cada petición a la API cuenta 1, también las consultas. Solo hay dos excepciones, que cuestan una petición por cada 50 registros, redondeando hacia arriba:

  • crear varios registros a la vez con POST /api/v2/schemas/{schemaId}/records;
  • borrar varios registros a la vez con POST /api/v2/schemas/{schemaId}/records:delete.
Registros en la petición Coste
De 1 a 50 1
De 51 a 100 2
500 10

Consultar el límite en las cabeceras

Las respuestas de la API incluyen tres cabeceras con el estado de la cuota. Con curl --include puedes verlas:

curl https://api-z2.zinkee.com/api/v2/schemas   
  --include   
  --header "Authorization: Bearer $ZINKEE_API_KEY"

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 1000
RateLimit-Remaining: 742
RateLimit-Reset: 1234
Cabecera Qué indica
RateLimit-Limit Peticiones permitidas en la ventana.
RateLimit-Remaining Peticiones que quedan en la ventana actual.
RateLimit-Reset Segundos que faltan para que termine la ventana y se restablezca la cuota.

En el ejemplo, al workspace le quedan 742 de sus 1000 peticiones y la cuota se restablece dentro de 1234 segundos, algo más de 20 minutos. Las cifras son ilustrativas: lee siempre las de tu workspace en las cabeceras.

Las cabeceras siguen la forma de tres campos del borrador del IETF RateLimit header fields for HTTP (draft-ietf-httpapi-ratelimit-headers, hasta la versión -06).

Respuestas sin estas cabeceras

  • Las respuestas 401 y 403, cuando falta la credencial, no es válida o no permite la operación, no las incluyen ni consumen cuota. Consulta Autenticación y permisos. Tampoco las incluye la respuesta 503 de un workspace en mantenimiento.
  • Si en ese momento no se puede comprobar el límite, la respuesta puede llegar sin ellas. En ese caso, la petición no se limita.

Haz que tu integración funcione aunque falten.

Qué responde la API al superar el límite

Se agota la cuota de la ventana

Cuando se agota la cuota, la API rechaza las peticiones con el código 429 y el motivo rate_limit hasta que termina la ventana. La respuesta incluye la cabecera Retry-After, con los segundos que debes esperar, el mismo valor que RateLimit-Reset, y las cabeceras de la cuota con RateLimit-Remaining: 0:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1234
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 1234

{
  "status": 429,
  "error": "TOO_MANY_REQUESTS",
  "reason": "rate_limit",
  "message": "Rate limit of 1000 requests per 3600 seconds reached for this workspace; it resets in 1234 seconds.",
  "action": "Wait the seconds in the Retry-After header, then retry.",
  "retryable": true,
  "path": "/api/v2/schemas/2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e/records",
  "requestId": "6f1d9c2a-0b7e-4f4c-8a3d-5e2b1c9f7a10",
  "timestamp": "2026-10-28T10:15:00Z"
}

Una petición cuesta más que todo el límite

Si una sola petición cuesta más que el límite completo del workspace, esperar no sirve: no cabría en ninguna ventana. Por ejemplo, crear 1500 registros a la vez cuesta 30 peticiones; con un límite de 20 peticiones por ventana, la API la rechaza con el código 429 y el motivo rate_limit_cost_exceeds_limit. La respuesta no incluye Retry-After y retryable es false:

{
  "status": 429,
  "error": "TOO_MANY_REQUESTS",
  "reason": "rate_limit_cost_exceeds_limit",
  "message": "This request costs 30 requests, more than the limit of 20 requests per 60 seconds of this workspace.",
  "action": "Split the batch into smaller requests and retry.",
  "retryable": false,
  "path": "/api/v2/schemas/2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e/records",
  "requestId": "9a4f2c7e-3b1d-4e8a-b6c5-1d7e3f9a2b64",
  "timestamp": "2026-10-28T10:15:00Z"
}

Un lote no cabe en lo que queda

Un lote que cuesta más de lo que queda en la ventana recibe el mismo 429 con el motivo rate_limit y Retry-After, y no se crea ni se borra ningún registro. En este caso RateLimit-Remaining indica lo que sigue quedando, que puede ser más de 0: espera a que termine la ventana o envía lotes más pequeños que quepan en lo que queda.

Los errores tienen el formato habitual de la API. Usa el campo reason para decidir qué hacer; message y action describen el error en inglés.

Qué hacer

Situación Qué hacer
RateLimit-Remaining se acerca a 0. Reduce el ritmo, por ejemplo repartiendo las peticiones que quedan entre los segundos de RateLimit-Reset.
429 con el motivo rate_limit. Espera los segundos que indica Retry-After y reintenta la misma petición.
429 con el motivo rate_limit_cost_exceeds_limit. No repitas la petición tal cual: divide el lote en peticiones más pequeñas, por ejemplo de 50 registros.

Además:

  • Agrupa los registros al crearlos o borrarlos: una petición con hasta 50 registros cuesta lo mismo que una con uno solo.
  • Recuerda que la cuota es del workspace. Si varias integraciones trabajan con el mismo workspace, todas consumen de la misma cuota.

Reintentar un 429 sin duplicar cambios

La API responde 429 antes de hacer nada con la petición, así que reintentarla es siempre seguro, aunque no envíes la cabecera Idempotency-Key. Si la envías, la respuesta 429 no guarda la clave: el reintento con la misma clave se ejecuta con normalidad. Consulta cómo usar la cabecera en Reintentar peticiones sin duplicar cambios.

Con la CLI de Zinkee

Desde la versión 0.1.62, la CLI de Zinkee gestiona el límite por ti:

  • Si la API responde 429 con un Retry-After de 30 segundos o menos, la CLI muestra un aviso en la salida de errores (stderr), espera y reintenta automáticamente, con o sin --idempotency-key. Hace como máximo 3 intentos por petición y espera como mucho 60 segundos en total por comando.
  • En los demás casos, la CLI termina con el código de error rate_limited y el código de salida 4. Si la API envió Retry-After, el error incluye en details.retryAfterSeconds los segundos que debes esperar.

Consulta todos los parámetros y respuestas en la referencia de la API.