Saltar al contenido

Límite de API excedido en GitHub Actions: soluciones

Última actualización

API rate limit exceeded for installation ID en un registro de GitHub Actions significa que un paso llamó a la API de GitHub con el GITHUB_TOKEN del workflow y agotó su cuota horaria. Ese token está limitado a 1,000 solicitudes por hora por repositorio (15,000 para recursos de una cuenta de GitHub Enterprise Cloud). Las soluciones consisten en hacer menos llamadas, almacenar resultados en caché, autenticarse con un token más adecuado o esperar cuando GitHub lo indique. Las cifras proceden de la documentación de límites de frecuencia de la API REST de GitHub, revisada en octubre de 2026.

El mensaje exacto

HttpError: API rate limit exceeded for installation ID 12345678.
403 API rate limit exceeded for installation. If you reach out to GitHub Support for help, please include the request ID ...
You have exceeded a secondary rate limit. Please wait a few minutes before you try again.
rate limit exceeded

La primera forma corresponde al límite primario, que se alcanza cuando se agota la cuota de la hora. La forma "secondary rate limit" se refiere a patrones de solicitudes, no al total horario. Otras formas relacionadas: API rate limit exceeded for user ID ... (un token personal) y API rate limit exceeded for <IP> (But here's the good news: Authenticated requests get a higher rate limit) (una llamada sin ningún token).

Los límites aplicables

CredencialLímite
Sin token (por IP)60 solicitudes por hora
Token de acceso personal (usuario)5,000 por hora
Instalación de GitHub App5,000 por hora, con un aumento de hasta 12,500 según los repositorios y usuarios
GITHUB_TOKEN en Actions1,000 por hora por repositorio
GITHUB_TOKEN, cuenta de Enterprise Cloud15,000 por hora por repositorio

El límite de GITHUB_TOKEN lo comparten todas las ejecuciones de workflows de ese repositorio durante la misma hora. Un repositorio muy activo con muchos jobs puede agotarlo, aunque cada job solo haga unas decenas de llamadas.

Límites secundarios, según la documentación: no más de 100 solicitudes concurrentes, no más de 900 puntos por minuto en los endpoints REST y, en general, no más de 80 solicitudes que crean contenido por minuto y 500 por hora. GitHub indica que estos valores pueden cambiar sin previo aviso.

Causas, de la más probable a la menos probable

1. Una matriz o muchas ejecuciones que llaman a la API a la vez

Si 30 celdas de una matriz llaman cada una 40 veces a gh api o a una action de releases, son 1,200 solicitudes. Mueva la llamada a un único job y comparta el resultado.

2. Bucles sobre listas

El caso clásico es gh pr list seguido de un gh api por cada PR. Use una única llamada paginada o GraphQL, que agrupa muchos campos en una sola solicitud.

- run: gh pr list --state open --json number,title,labels --limit 200
  env:
    GH_TOKEN: ${{ github.token }}

3. Herramientas que descargan releases o comprueban versiones

Los gestores de versiones y las actions de configuración que consultan la API de Releases para obtener la última versión (asdf, alias de nvm, actions setup-* con latest) consumen el token. Fije las versiones o pase un token para que usen la caché o un límite autenticado.

4. Una llamada sin token

Las llamadas no autenticadas desde un runner comparten el límite de 60 por hora de la IP del runner. Pase siempre un token:

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

5. Bots y automatizaciones en el mismo repositorio

Dependabot, los etiquetadores, los bots de issues inactivos y las herramientas de release consumen la misma cuota del repositorio.

6. Límite secundario por ráfagas

Crear muchos comentarios, issues o estados en un bucle activa el límite secundario. Reduzca el ritmo con un sleep breve y nunca ejecute estas llamadas en paralelo.

Soluciones

Compruebe lo que queda

- run: gh api rate_limit --jq '.resources.core'
  env:
    GH_TOKEN: ${{ github.token }}

Según la documentación, las cabeceras de respuesta x-ratelimit-remaining y x-ratelimit-reset (segundos desde la época Unix) son la fuente fiable.

Use un token de GitHub App para automatizaciones intensivas

Una instalación de GitHub App tiene su propia cuota de 5,000 por hora (más en instalaciones grandes), separada del GITHUB_TOKEN del repositorio. La action create-github-app-token genera uno dentro del job:

- uses: actions/create-github-app-token@v1
  id: app
  with:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
- run: gh api repos/${{ github.repository }}/issues --paginate
  env:
    GH_TOKEN: ${{ steps.app.outputs.token }}

Tenga en cuenta que el mensaje de límite de un token de instalación también dice "installation ID", así que confirme qué token usa su paso.

Esperar cuando se alcanza el límite

Para los límites primarios, espere hasta x-ratelimit-reset. Para los límites secundarios, GitHub indica respetar retry-after si está presente; si no, espere al menos un minuto y luego aplique una espera exponencial. La documentación advierte además que seguir enviando solicitudes mientras se está limitado puede provocar el bloqueo de la integración.

for i in 1 2 3 4; do
  gh api repos/OWNER/REPO/issues && break
  sleep $((30 * i))
done

Reduzca las solicitudes

  • Use solicitudes condicionales con ETag y If-None-Match; una respuesta 304 no cuenta para el límite primario.
  • Solicite solo lo necesario con per_page=100 y filtros.
  • Almacene en caché los resultados de la API con actions/cache cuando cambien con poca frecuencia (consulte caché en GitHub Actions).
  • Ejecute los jobs programados con menos frecuencia y desplace los horarios de cron (generador de cron).

No es lo mismo que los límites de Docker o de caché

Si el error menciona toomanyrequests, consulte límite de descargas de Docker. Los límites de la API de caché (cargas por minuto) son independientes de este; consulte límites de caché. Los límites de frecuencia se aplican por token y no están relacionados con la velocidad del runner, así que cambiar de proveedor de runners no los modifica. Un proveedor como compiler.dev sigue utilizando su token de GitHub para las llamadas a la API de GitHub.

Cómo prevenirlo

  1. Utilice GITHUB_TOKEN solo para llamadas ligeras y un token de App para la automatización intensiva.
  2. Realice las llamadas a la API en un solo job, no en cada celda de la matriz.
  3. Prefiera GraphQL o las llamadas de listado paginadas en lugar de los bucles por elemento.
  4. Fije las versiones de las herramientas para que los pasos de configuración no consulten la API.
  5. Registre la cuota restante al final de los workflows con mucha actividad para detectar un aumento del consumo.

Preguntas frecuentes

¿Cuál es el límite de frecuencia de GITHUB_TOKEN?

1,000 solicitudes por hora por repositorio, y 15,000 para los recursos de una cuenta de GitHub Enterprise Cloud.

¿Cómo consulto mi límite de frecuencia en un workflow?

Ejecute gh api rate_limit con GH_TOKEN definido, o lea la cabecera x-ratelimit-remaining de cualquier respuesta de la API.

¿Qué es un límite de frecuencia secundario?

Un límite sobre patrones de solicitudes, como demasiadas solicitudes simultáneas o que crean contenido. Puede activarse aunque todavía le quede cuota por hora.

¿El límite se restablece cada hora?

Sí, la ventana se restablece en el momento indicado en x-ratelimit-reset.