Solución de problemas de API de REST

Errores de límite de tasa

GitHub aplica limitaciones de volumen para asegurarse de que la API permanezca disponible para todos los usuarios. Para más información, consulta Límites de tasa de la API REST.

Si supera su límite de tarifa principal, recibirá una respuesta 403 Forbidden o 429 Too Many Requests y el encabezado x-ratelimit-remaining será 0. Si supera una limitación de volumen secundaria, recibirá una respuesta 403 Forbidden o 429 Too Many Requests y un mensaje de error que indicará que ha superado una limitación de volumen secundaria.

Si recibe un error de limitación de volumen, debe dejar de realizar solicitudes temporalmente según estas directrices:

Si el encabezado de respuesta retry-after está presente, no debes reintentar la solicitud hasta que hayan transcurrido los segundos indicados.
Si el encabezado x-ratelimit-remaining es 0, no realice otra solicitud hasta después de la hora especificada en el encabezado x-ratelimit-reset. El encabezado x-ratelimit-reset está en segundos de época UTC.
De lo contrario, espere al menos un minuto antes de volver a intentarlo. Si la solicitud sigue produciendo un error debido a una limitación de volumen secundaria, espere un período de tiempo exponencialmente creciente entre reintentos y genere un error después de un número específico de reintentos.

Continuar realizando solicitudes mientras esté bajo restricciones de tasa puede resultar en que se prohíba su integración.

Para obtener más información sobre cómo evitar superar las limitaciones de volumen, consulta Procedimientos recomendados para usar la API de REST.

          `404 Not Found` para un recurso existente

Si realiza una solicitud para acceder a un recurso privado y la solicitud no está autenticada correctamente, recibirá una respuesta 404 Not Found. GitHub usa una respuesta 404 Not Found en lugar de una respuesta 403 Forbidden para evitar confirmar la existencia de repositorios privados.

Si recibe una respuesta 404 Not Found cuando sabe que el recurso que solicita existe, compruebe la autenticación. Por ejemplo:

Si usa un personal access token (classic), asegúrese de que:
- El token tiene los ámbitos necesarios para usar el punto de conexión. Para más información, consulta Ámbitos para las aplicaciones de OAuth y Administración de tokens de acceso personal.
- El propietario del token tiene los permisos necesarios para usar el punto de conexión. Por ejemplo, si los propietarios de la organización son los únicos que pueden usar un punto de conexión, solo los usuarios que sean propietarios de la organización afectada podrán usar el punto de conexión.
- El token no ha expirado ni se ha revocado. Para más información, consulta Vencimiento y revocación de tokens.
Si usa un fine-grained personal access token, asegúrese de que:
- El token tiene los permisos necesarios para usar el punto de conexión. Para obtener más información sobre los permisos necesarios, consulte la documentación del punto de conexión.
- El propietario del recurso que se especificó para el token coincide con el propietario del recurso al que afectará el punto de conexión. Para más información, consulta Administración de tokens de acceso personal.
- El token tiene acceso a cualquier repositorio privado que afecte el punto de conexión. Para más información, consulta Administración de tokens de acceso personal.
- El propietario del token tiene los permisos necesarios para usar el punto de conexión. Por ejemplo, si los propietarios de la organización son los únicos que pueden usar un punto de conexión, solo los usuarios que sean propietarios de la organización afectada podrán usar el punto de conexión.
- El token no ha expirado ni se ha revocado. Para más información, consulta Vencimiento y revocación de tokens.
Si usa un token de acceso de instalación de GitHub App, asegúrese de que:
- La aplicación GitHub App tiene los permisos necesarios para usar el punto de conexión. Para obtener más información sobre los permisos necesarios, consulte la documentación del punto de conexión.
- El punto de conexión solo afecta a los recursos propiedad de la cuenta donde se ha instalado GitHub App.
- La aplicación GitHub App tiene acceso a los repositorios a los que afectará el punto de conexión.
- El token no ha expirado ni se ha revocado. Para más información, consulta Vencimiento y revocación de tokens.
Si usa un token de acceso de usuario de GitHub App, asegúrese de que:
- La aplicación GitHub App tiene los permisos necesarios para usar el punto de conexión. Para obtener más información sobre los permisos necesarios, consulte la documentación del punto de conexión.
- El usuario que autorizó el token tiene los permisos necesarios para usar el punto de conexión. Por ejemplo, si los propietarios de la organización son los únicos que pueden usar un punto de conexión, solo los usuarios que sean propietarios de la organización afectada podrán usar el punto de conexión.
- La aplicación GitHub App tiene acceso a los repositorios a los que afectará el punto de conexión.
- El usuario tiene acceso a los repositorios a los que afectará el punto de conexión.
- El usuario ha aprobado los permisos actualizados para la aplicación GitHub App. Para más información, consulta Aprobación de permisos actualizados para una aplicación de GitHub.
Si usa un token de acceso de usuario de OAuth app, asegúrese de lo siguiente:
- El token tiene los ámbitos necesarios para usar el punto de conexión. Para más información, consulta Ámbitos para las aplicaciones de OAuth.
- El usuario que autorizó el token tiene los permisos necesarios para usar el punto de conexión. Por ejemplo, si los propietarios de la organización son los únicos que pueden usar un punto de conexión, solo los usuarios que sean propietarios de la organización afectada podrán usar el punto de conexión.
- La organización no ha bloqueado el acceso a aplicaciones OAuth si estás utilizando un punto de conexión que afectará a los recursos propiedad de la organización. Los propietarios de la aplicación no pueden ver si su aplicación está bloqueada, pero pueden indicar a los usuarios de la aplicación que comprueben esto. Para obtener más información, consulta Acerca de las restricciones de acceso a aplicaciones OAuth.
- El token no ha expirado ni se ha revocado. Para más información, consulta Vencimiento y revocación de tokens.
Si usa GITHUB_TOKEN en un flujo de trabajo de GitHub Actions, asegúrese de que:
- El punto de conexión solo afecta a los recursos que pertenecen al repositorio donde se ejecuta el flujo de trabajo. Si tiene que acceder a recursos externos a ese repositorio, como recursos que pertenecen a una organización o recursos que pertenecen a otro repositorio, debe usar un personal access token o un token de acceso para un GitHub App.

Para obtener más información acerca de la autenticación, consulta Autenticación en la API REST.

También debe comprobar si hay errores tipográficos en la dirección URL. Por ejemplo, si agrega una barra diagonal final al punto de conexión, se producirá una excepción 404 Not Found. Puede consultar la documentación de referencia del punto de conexión para confirmar que tiene la dirección URL correcta.

Además, los parámetros de ruta de acceso deben estar codificados en formato de dirección URL. Por ejemplo, las barras diagonales del valor del parámetro deben reemplazarse por %2F. Si no codificas correctamente ninguna barra diagonal en el nombre del parámetro, se malinterpretará la dirección URL del punto de conexión.

Faltan resultados

La mayoría de los puntos de conexión que devuelven una lista de recursos admiten la paginación. De manera predeterminada, en la mayoría de estos puntos de conexión, solo se devuelven los primeros 30 recursos. Para ver todos los recursos, es necesario navegar por las páginas de los resultados. Para más información, consulta Uso de la paginación en la API de REST.

Si usa la paginación correctamente y sigue sin ver todos los resultados esperados, debe confirmar que las credenciales de autenticación que usó tengan acceso a todos los recursos esperados. Por ejemplo, si usa un token de acceso de instalación de GitHub App, si a la instalación solo se le concedió acceso a un subconjunto de repositorios de una organización, cualquier solicitud de todos los repositorios de esa organización devolverá únicamente los repositorios a los que puede acceder la instalación de la aplicación.

Se requiere autenticación al usar la autenticación básica

No se admite la autenticación básica con su nombre de usuario y contraseña. En su lugar, debes usar un personal access token o un token de acceso para una aplicación GitHub App o OAuth app. Para más información, consulta Autenticación en la API REST.

Tiempos de expiración

Si GitHub tarda más de 10 segundos en procesar una solicitud de la API, GitHub terminará la solicitud y recibirá una respuesta de tiempo de espera excedido y un mensaje "Server Error".

GitHub se reserva el derecho de cambiar la ventana de tiempo de espera para proteger la velocidad y fiabilidad de la API.

Puede comprobar el estado de la API de REST en githubstatus.com para determinar si el tiempo de espera excedido se debe a un problema con la API. También puede intentar simplificar la solicitud o probar la solicitud más adelante. Por ejemplo, si solicita 100 elementos en una página, puede intentar solicitar menos elementos.

Recurso no accesible

Si usa una aplicación GitHub App o fine-grained personal access token y recibe un error "La integración no puede acceder al recurso"o "personal access token no puede acceder al recurso", el token no tiene permisos suficientes. Para obtener más información sobre los permisos necesarios, consulte la documentación del punto de conexión.

Puede usar el encabezado X-Accepted-GitHub-Permissions para identificar los permisos necesarios para acceder al punto de conexión de la API REST.

El valor del encabezado X-Accepted-GitHub-Permissions es una lista separada por comas de los permisos necesarios para usar el punto de conexión. En ocasiones, puede elegir entre varios conjuntos de permisos. En estos casos, varias listas separadas por comas se separarán mediante un punto y coma.

Por ejemplo:

          `X-Accepted-GitHub-Permissions: contents=read` significa que la GitHub App o fine-grained personal access token necesita acceso de lectura a los permisos de contenido.

          `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` significa que GitHub App o fine-grained personal access token necesita acceso de escritura al permiso de solicitud de incorporación de cambios y acceso de lectura al permiso de contenido.

          `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` significa que GitHub App o fine-grained personal access token necesita acceso de lectura al permiso de solicitud de incorporación de cambios y acceso de lectura al permiso de contenido o acceso de lectura al permiso de incidencias y acceso de lectura al permiso de contenido.

Problemas al analizar JSON

Si envía JSON no válido en el cuerpo de la solicitud, puede recibir una respuesta 400 Bad Request y un mensaje de error "Problemas al analizar JSON". Puede usar un validador de linter o JSON para ayudarle a identificar errores en el JSON.

El cuerpo debe ser un objeto JSON

Si el punto de conexión espera un objeto JSON y no aplica formato al cuerpo de la solicitud como un objeto JSON, puede recibir una respuesta 400 Bad Request y un mensaje de error "El cuerpo debe ser un objeto JSON".

Solicitud no válida

Si omite los parámetros necesarios o usa el tipo incorrecto para un parámetro, puede recibir una respuesta 422 Unprocessable Entity y un mensaje de error "Solicitud no válida". Por ejemplo, obtendrá este error si especifica un valor de parámetro como una matriz, pero el punto de conexión espera una cadena. Puede consultar la documentación de referencia del punto de conexión para comprobar que usa los tipos de parámetro correctos y que incluye todos los parámetros necesarios.

Error de validación

Si no se pudo procesar la solicitud, puede recibir una respuesta 422 Unprocessable Entity y un mensaje de error "Error de validación". El cuerpo de la respuesta incluirá una propiedad errors, que incluye una propiedad code para ayudarle a diagnosticar el problema.

Código	Descripción
`missing`	Un recurso no existe.
`missing_field`	No se especificó un parámetro necesario. Revise la documentación del punto de conexión para ver qué parámetros son necesarios.
`invalid`	El formato de un parámetro no es válido. Revise la documentación del punto de conexión para encontrar información más específica.
`already_exists`	Otro recurso tiene el mismo valor que uno de los parámetros. Esto puede suceder en recursos que deben tener claves únicas (tales como nombres de etiqueta).
`unprocessable`	Los parámetros proporcionados no eran válidos.
`custom`	Consulte la propiedad `message` para diagnosticar el error.

No es una versión compatible

Debe usar el encabezado X-GitHub-Api-Version para especificar una versión de API. Por ejemplo:

curl --encabezado "X-GitHub-Api-Version:2026-03-10" https://api.github.com/zen

Si especifica una versión que no existe, recibirá un error 400 Bad Request y un mensaje sobre la versión que no se admite.

Para más información, consulta Versiones de API.

        [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api)

        [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks)

        [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)

En este artículo