Readme stats no funciona: arreglá 503, 403 y rate limit

En pocas palabras: Tu readme stats falla porque la instancia pública que dibuja la card está pausada (503 DEPLOYMENT_PAUSED, tras terminar el sponsorship de Vercel), limitada por rate limit o rechaza pedidos (403 en streak). La solución duradera: generar los SVG con GitHub Actions y commitearlos en USERNAME/USERNAME.

Si tu readme stats no funciona y ves un 503, un 403 o una caja gris con “Something went wrong”, casi siempre falla la instancia pública que dibuja la card, no tu Markdown. El arreglo duradero es generar los SVG con GitHub Actions dentro de tu propio repo.

GitHub Readme Stats es un proyecto de código abierto, creado por anuraghazra, que genera como imagen SVG, a partir de una URL con tu usuario, tarjetas con estadísticas de GitHub (estrellas, commits, pull requests, lenguajes más usados) para pegar en el README de tu perfil. Según su propio README al 14/10/2026, el repositorio original ya no se mantiene y apunta a GitHub Stats Extended como sucesor.

¿Cómo saber si falla mi README o el servicio que dibuja la card?

Copiá la URL de la imagen desde tu README y abrila directo en el navegador, o corré un curl -I contra el endpoint. El código de respuesta te dice de quién es el problema en menos de un minuto, según el diagnóstico de la guía de dev.to.

curl -I "https://github-readme-stats.vercel.app/api?username=TU_USUARIO"
curl -I "https://streak-stats.demolab.com/?user=TU_USUARIO"

Un 200 con image/svg+xml y una card normal significa servicio sano: mirá tu README o una copia cacheada en GitHub. Un 200 con el SVG de error apunta a rate limit. Un 503 es instancia caída o pausada, y un 403 es un endpoint que rechaza el pedido.

Síntoma	Causa probable	Arreglo más rápido
503 / DEPLOYMENT_PAUSED	Instancia pública pausada	GitHub Actions o self-host
Card “Something went wrong”	Rate limit de la API de GitHub o error al traer datos	Token propio (Actions o self-host)
403 en la streak card	El endpoint público bloquea pedidos	Action de Streak Stats
Ícono de imagen rota, sin error	Respuesta lenta o fallo cacheado detrás del proxy de imágenes de GitHub	SVG estático en tu repo
Datos equivocados	Typo, usuario incorrecto o caché	Revisar la URL y esperar que venza la caché

Ojo con confiarte: la fuente reporta que el 14/10/2026 ambos endpoints devolvían 200, pero también aclara que se caen de vez en cuando.

¿Por qué mi readme stats no funciona y muestra 503, 403 o “Something went wrong”?

Hay cuatro causas documentadas, y casi todas son del lado del servicio público, no tuyo. Sirve saber cuál te toca porque cada una tiene su arreglo. Si además estás armando otros proyectos, te puede servir nuestra guía para publicar un proyecto React con Vite.

• 503 por deployment pausado. En el issue #3851, consultado el 14/10/2026, los mantenedores explican que terminó el sponsorship de Vercel y recomiendan Actions o self-host. Esa explicación viene de un colaborador en un issue, no de un comunicado oficial de Vercel.
• Rate limits. El README dice que la instancia pública es “best-effort and can be unreliable due to rate limits and traffic spikes”. Miles de perfiles comparten un mismo pool de requests a la API de GitHub; cuando se agota, te toca la card de error.
• 403 en Streak Stats. En el issue #872 usuarios reportaron 403 en todos los endpoints públicos. Está cerrado, pero puede repetirse.
• Imagen rota sin error. GitHub sirve las imágenes del README por su proxy (camo). Si la card tarda, puede no aparecer; hay reportes en los issues #754 y #792 de streak.

Los issues #4737 y #4798 (“not working again ?”) siguen abiertos según la guía consultada el 14/10/2026. Mi lectura: si tu perfil depende de una instancia que su propio README califica de “best-effort”, la próxima caída es cuestión de tiempo, no de si pasa.

¿Cómo generar las cards con GitHub Actions para no depender de un servicio público?

Creá un workflow en tu repo USERNAME/USERNAME que construya los SVG con una action oficial, los commitee a una carpeta y hacé que el README apunte a esos archivos. Así no hay ningún servicio externo entre tu perfil y la imagen. Es la opción que la fuente marca como la que mejor aguanta.

Guardalo como .github/workflows/grs.yml. Está adaptado de el README de la action:

name: Update README cards
on:
 schedule:
 - cron: "0 0 * * *"
 workflow_dispatch:
jobs:
 build:
 runs-on: ubuntu-latest
 permissions:
 contents: write
 steps:
 - uses: actions/checkout@v6
 - uses: stats-organization/github-readme-stats-action@v2
 with:
 card: stats
 options: username=${ github.repository_owner }&show_icons=true
 path: profile/stats.svg
 token: ${ secrets.GITHUB_TOKEN }
 - uses: stats-organization/github-readme-stats-action@v2
 with:
 card: top-langs
 options: username=${ github.repository_owner }&layout=compact
 path: profile/top-langs.svg
 token: ${ secrets.GITHUB_TOKEN }
 - name: Commit cards
 run: |
 git config user.name "github-actions[bot]"
 git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 git add profile/*.svg
 git commit -m "Update README cards" || exit 0
 git push

En el README, usá ![Stats](./profile/stats.svg). Algunos detalles que cambian el resultado:

• Repos privados. Necesitás un PAT con scopes repo y read:user, guardado como secret. Nunca lo pegues en el YAML.
• Streak card. Usá DenverCoder1/github-readme-streak-stats@v1 con user= (no username=). El token solo hace falta para contribuciones privadas.
• Modo claro y oscuro. Generá un segundo SVG con theme=dark y elegilo con <picture> y prefers-color-scheme.
• Límite real. Las cards se actualizan solo cuando corre el workflow, una vez por día en este ejemplo. Para un perfil alcanza.
• Costos. Las fuentes no traen datos de precios ni cuotas de Actions. Revisá la documentación de facturación de GitHub antes de dar por sentado que es gratis en tu caso.

Una inferencia mía a partir del README de la action: la opción fail_on_error viene en false por defecto, así que ante un rate limit el workflow escribe la card de error y el paso siguiente la commitea. Ponerla en true hace que el job falle y tu último SVG bueno quede intacto. Relacionado: montar tu propia instancia gratis en Vercel.

¿Cómo hacer self-host de github-readme-stats en Vercel?

Forkeás el repo, lo importás en Vercel, cargás un PAT de GitHub como variable de entorno PAT_1, desplegás y cambiás el dominio en tu README por el de tu app. Es el camino si querés cards que se actualicen en vivo y no una vez por día.

1. Hacé un fork (el README original todavía trae la guía de Vercel; GitHub Stats Extended tiene sus propios docs de deploy).
2. Importá el fork en Vercel.
3. Creá el PAT y agregalo como PAT_1.
4. Desplegá y cambiá la URL: https://TU-APP.vercel.app/api?username=TU_USUARIO&cache_seconds=21600.

El último paso es el que más se olvida. El artículo fuente cita el issue #4747, donde un fork propio parecía roto porque el README seguía apuntando a la URL pública. Si preferís otro proveedor para alojar la instancia, el README de la fuente prevé deploys en otras plataformas; para un servidor en Argentina podés mirar donweb.com.

Sobre la caché: cache_seconds acepta de 21600 a 86400 y el default es 21600. En tu instancia podés fijar CACHE_SECONDS. Ahora bien, el README también lista horas por defecto por tipo de card (stats 24 horas, top languages 144 horas), así que un cambio puede tardar días en verse. En el plan gratuito de Vercel, tu propio tráfico cuenta contra tus propios límites.

¿Por qué la card de lenguajes muestra cualquier cosa?

La card de top languages mira solo tus primeros 100 repos y ordena por bytes, así que un notebook de Jupyter enorme puede desplazar al resto. La guía propone hide=jupyter%20notebook, exclude_repo=old-fork y size_weight=0.5&count_weight=0.5, la combinación que recomienda el README. Para que GitHub no cuente notebooks, agregá *.ipynb linguist-vendored en .gitattributes.

¿Qué alternativas hay si no querés mantener un workflow ni un deploy?

La alternativa mantenida es GitHub Stats Extended, el sucesor que el README original recomienda y que tiene instancia pública propia. También existen instancias comunitarias de terceros, pero nadie promete que sigan arriba. Ya lo cubrimos antes, cuando comparamos Vercel con AWS Amplify.

Opción	Cuándo se actualiza	Qué tenés que mantener	Dato clave
Instancia pública original	En vivo, con caché	Nada	“Best-effort”, sin mantenimiento
Actions + SVG en tu repo	Cuando corre el workflow	Un archivo YAML	Sin servicio externo en medio
Self-host en Vercel	En vivo, según caché	Un deploy y un PAT	Tu uso cuenta contra tus límites
GitHub Stats Extended (instancia pública)	En vivo	Nada	Sucesor mantenido
GitHubCard (hosteado)	En vivo	Nada	El autor de la fuente trabaja ahí

Transparencia: el autor de la guía fuente declara que trabaja en GitHubCard, un editor hosteado de cards con embed de una línea. Lo cito como dato con ese conflicto de interés, no como recomendación. Hasta él concluye que, si la card tiene que estar siempre, un SVG commiteado por una Action sigue siendo lo más seguro.

¿Qué está confirmado y qué no?

• Confirmado en las fuentes: el repo original figura sin mantenimiento; la instancia pública se describe como “best-effort”; el issue #3851 documenta la pausa del deploy; el #872 de streak está cerrado.
• Reportado por el autor de la guía: ambos endpoints devolvían 200 el 14/10/2026.
• No confirmado: la causa exacta de cada caída puntual, si camo explica cada imagen rota, cuándo (o si) se resuelven los issues abiertos #4737 y #4798, y los costos de Actions en tu cuenta.

Qué podés decidir con esto: migrar a una opción bajo tu control. Qué no: predecir cuándo vuelve a caerse el servicio público.

¿Cómo verificar que el arreglo quedó firme?

Es una propuesta editorial, no un procedimiento de las fuentes. Corré el workflow a mano con workflow_dispatch, abrí el SVG resultante en tu repo y comprobá que no sea la card de error. Después mirá tu perfil en una ventana privada y revisá a los pocos días que el commit diario del bot siga apareciendo.

Errores comunes al arreglar las cards

• Dejar la URL pública en el README. Armás tu instancia, anda bárbaro, y el perfil sigue roto porque apunta al dominio viejo (el caso del #4747). Cambiá el dominio.
• Mezclar parámetros. Streak Stats usa user y github-readme-stats usa username. Un typo, una cuenta renombrada o un \& copiado de una doc también rompen todo.
• Pegar el token en el YAML. Va como secret del repositorio, siempre.
• Esperar privados con el token por defecto. Para repos privados hace falta un PAT con repo y read:user.
• Dar por roto algo que está cacheado. Con horas de caché por defecto, el cambio puede tardar en verse. Esperá antes de tocar nada más.

Preguntas Frecuentes

¿Por qué mi github readme stats no funciona y muestra error 503?

Un 503 con DEPLOYMENT_PAUSED indica que la instancia pública de Vercel está pausada. Según el issue #3851, consultado el 14/10/2026, terminó el sponsorship de Vercel y los mantenedores recomiendan usar GitHub Actions o hacer self-host. Más contexto en otras plataformas de hosting además de Vercel.

¿Cómo arreglar la card de GitHub que dice “Something went wrong”?

Usá tu propio token. Ese mensaje suele ser rate limit de la API de GitHub o un error al traer los datos, y lo resolvés generando la card con GitHub Actions o con tu instancia propia, donde el límite es tuyo y no del pool compartido.

¿Por qué la streak stats de mi perfil da error 403?

El endpoint público está rechazando los pedidos. En el issue #872 de Streak Stats, usuarios reportaron 403 en todos los endpoints públicos; el issue está cerrado, pero puede repetirse. La salida es la Action de Streak Stats que commitea un SVG a tu repo.

¿Cómo hacer self-host de github-readme-stats en Vercel?

Forkeá el repo, importalo en Vercel, agregá un PAT como variable PAT_1, desplegá y cambiá el dominio en tu README por el de tu app. Si la card sigue rota, revisá que la URL ya no apunte a la instancia pública.

¿GitHub Actions es gratis para generar las cards de mi perfil?

Las fuentes consultadas no traen datos de precios ni cuotas de GitHub Actions, así que no puedo afirmarlo. Revisá la documentación oficial de facturación de GitHub para tu tipo de cuenta antes de depender del workflow.

Conclusión

Cuando el readme stats no funciona, el problema casi nunca es tu Markdown: es una instancia pública que su propio repositorio describe como “best-effort” y sin mantenimiento. Diagnosticá con curl -I, y si querés dejar de pensar en esto, pasá a un workflow de Actions con fail_on_error activado que commitee los SVG a tu repo. Si necesitás datos en vivo, hacé self-host y acordate de cambiar la URL. Nada de esto depende de que alguien más pague el hosting.

Fuentes

• GitHub Readme Stats – repositorio y README original
• Issue #3851 – Public deployment paused
• github-readme-stats-action – documentación de la Action
• Streak Stats, issue #872 – errores 403 en endpoints públicos
• dev.to – guía para arreglar 503, rate limits, 403 e imágenes rotas