Solución de problemas de API de REST

Errores de limitación de volumen

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

Si supera la limitación de volumen 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 tiene una limitación de volumen puede dar lugar a la prohibición de la integración.

Para obtener más información sobre cómo evitar superar las limitaciones de volumen, consulte "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 obtener más información, vea «Á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, consulte "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, vea «Permisos necesarios para los tokens de acceso personal específicos».
- 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 obtener más información, vea «Administración de tokens de acceso personal».
- El token tiene acceso a los repositorios privados a los que afectará el punto de conexión. Para obtener más información, vea «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, vea «Permisos que requieren las Github Apps».
- 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 obtener más información, vea «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, vea «Permisos que requieren las Github Apps».
- 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 obtener más información, vea «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 que:
- El token tiene los ámbitos necesarios para usar el punto de conexión. Para obtener más información, vea «Á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 la aplicación de OAuth, si usa un punto de conexión que afectará a los recursos propiedad de una 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 más información, consulte "Acerca de las restricciones de acceso a aplicaciones OAuth".
- El token no ha expirado ni se ha revocado. Para obtener más información, vea «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, vea "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.

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, debe paginar los resultados. Para obtener más información, vea «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 obtener más información, vea «Autenticación en la API REST».

Tiempos de espera

Si a GitHub le toma más de 10 segundos procesar una solicitud de la API, GitHub terminará la solicitud y recibirá una respuesta de tiempo de espera excedido y un mensaje "Error de servidor".

GitHub se reserva el derecho de cambiar la ventana de tiempo de espera para proteger la velocidad y confiabilidad 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 para cada punto de conexión, consulte "Permisos que requieren las Github Apps" y "Permisos necesarios para los tokens de acceso personal específicos".

Puede usar el encabezado X-Accepted-GitHub-Permissions para identificar los permisos necesarios para acceder al punto de conexión de la API de 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 GitHub App o fine-grained personal access token necesitan acceso de lectura al permiso de contenido.
X-Accepted-GitHub-Permissions: pull_requests=write,contents=read significa que sus GitHub App o fine-grained personal access token necesitan acceso de escritura a la solicitud de incororació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 sus GitHub App o fine-grained personal access token necesitan acceso de lectura a la 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

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

curl --encabezado "X-GitHub-Api-Version:2022-11-28" 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 obtener más información, vea «Versiones de API».