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
| Credencial | Límite |
|---|---|
| Sin token (por IP) | 60 solicitudes por hora |
| Token de acceso personal (usuario) | 5,000 por hora |
| Instalación de GitHub App | 5,000 por hora, con un aumento de hasta 12,500 según los repositorios y usuarios |
GITHUB_TOKEN en Actions | 1,000 por hora por repositorio |
GITHUB_TOKEN, cuenta de Enterprise Cloud | 15,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
ETagyIf-None-Match; una respuesta 304 no cuenta para el límite primario. - Solicite solo lo necesario con
per_page=100y filtros. - Almacene en caché los resultados de la API con
actions/cachecuando 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
- Utilice
GITHUB_TOKENsolo para llamadas ligeras y un token de App para la automatización intensiva. - Realice las llamadas a la API en un solo job, no en cada celda de la matriz.
- Prefiera GraphQL o las llamadas de listado paginadas en lugar de los bucles por elemento.
- Fije las versiones de las herramientas para que los pasos de configuración no consulten la API.
- 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.
Relacionado
- Límite de pull de Docker Hub en GitHub Actions: solucionesSolucione "toomanyrequests: You have reached your pull rate limit" en GitHub Actions: límites de Docker Hub, docker/login-action, mirrors y alternativas GHCR.
- Cache Service Responded With 429: Cómo solucionarloSolucione "Failed to restore: Cache service responded with 429" en GitHub Actions: demasiadas solicitudes de caché. Actualice actions/cache y restaure y guarde una vez.
- fatal: could not read Username for github.com: SoluciónSolucione "fatal: could not read Username for 'https://github.com'" en GitHub Actions: repos privados, submódulos y dependencias git necesitan un token.
- Archivo de flujo de trabajo no válido: cómo solucionar el error de sintaxis YAMLCorrija "Invalid workflow file" y "You have an error in your yaml syntax" en GitHub Actions: sangría, valor inesperado, expresiones erróneas, con actionlint.