Skip to main content

Límites de volumen y límites de nodo para GraphQL API

La API de GraphQL de GitHub cuenta con limitaciones para la protección contra las llamadas excesivas o abusivas a los servidores de GitHub.

Límite de nodos

Para pasar la validación del esquema, todas las llamadas de GraphQL API deben cumplir estos estándares:

  • Los clientes deben proporcionar un argumento first o last en cualquier conexión.
  • Los valores de first y last deben estar comprendidos entre 1 y 100.
  • Las llamadas individuales no pueden solicitar más de un total de 500 000 nodos.

Calcular los nodos en una llamada

Estos dos ejemplos te muestran cómo calcular los nodos totales en una llamada.

  1. Consulta simple:

    query {
      viewer {
        repositories(first: 50) {
          edges {
            repository:node {
              name
    
              issues(first: 10) {
                totalCount
                edges {
                  node {
                    title
                    bodyHTML
                  }
                }
              }
            }
          }
        }
      }
    }

    Cálculo:

    50         = 50 repositories
     +
    50 x 10  = 500 repository issues
    
                = 550 total nodes
  2. Consulta compleja:

    query {
      viewer {
        repositories(first: 50) {
          edges {
            repository:node {
              name
    
              pullRequests(first: 20) {
                edges {
                  pullRequest:node {
                    title
    
                    comments(first: 10) {
                      edges {
                        comment:node {
                          bodyHTML
                        }
                      }
                    }
                  }
                }
              }
    
              issues(first: 20) {
                totalCount
                edges {
                  issue:node {
                    title
                    bodyHTML
    
                    comments(first: 10) {
                      edges {
                        comment:node {
                          bodyHTML
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
    
        followers(first: 10) {
          edges {
            follower:node {
              login
            }
          }
        }
      }
    }

    Cálculo:

    50              = 50 repositories
     +
    50 x 20       = 1,000 pullRequests
     +
    50 x 20 x 10 = 10,000 pullRequest comments
     +
    50 x 20       = 1,000 issues
     +
    50 x 20 x 10 = 10,000 issue comments
     +
    10              = 10 followers
    
                     = 22,060 total nodes

Límite de volumen principal

GraphQL API asigna puntos a cada consulta y limita los puntos que puede usar dentro de un período de tiempo específico. Este límite ayuda a evitar ataques por denegación de servicio y abuso, y garantiza que la API siga estando disponible para todos los usuarios.

REST API también tiene un límite de volumen principal independiente. Para obtener más información, vea «Límites de volumen de la API de REST».

En general, puede calcular el límite de volumen de GraphQL API en función del método de autenticación.

  • Para los usuarios: 5000 puntos por hora por usuario. Esto incluye las solicitudes realizadas con un personal access token, así como las solicitudes realizadas por un GitHub App o OAuth app en nombre de un usuario que autorizó la app. Las solicitudes realizadas en nombre de un usuario por una GitHub App que pertenece a una organización de GitHub Enterprise Cloud tienen un límite de volumen superior de 10 000 puntos por hora. De forma parecida, las solicitudes realizadas en su nombre por una OAuth app que aprueba una organización de GitHub Enterprise Cloud o pertenece a ella tienen un límite de volumen superior de 10 000 puntos por hora, si usted es miembro de la organización de GitHub Enterprise Cloud.
  • Para las instalaciones de GitHub App que no sean en una organización de GitHub Enterprise Cloud: 5000 puntos por hora por instalación. Las instalaciones que tienen más de 20 repositorios reciben otros 50 puntos adicionales por hora para cada repositorio. Las instalaciones que se encuentran en una organización que tienen más de 20 usuarios reciben otros 50 puntos por hora para cada usuario. El límite de volumen no puede superar los 12 500 puntos por hora. El límite de volumen de los tokens de acceso de usuario (en lugar de los tokens de acceso de instalación) viene determinado por el límite de volumen principal para los usuarios.
  • Para instalaciones de GitHub App en una organización de GitHub Enterprise Cloud: 10 000 puntos por hora por instalación. El límite de volumen de los tokens de acceso de usuario (en lugar de los tokens de acceso de instalación) viene determinado por el límite de volumen principal para los usuarios.
  • Para OAuth apps: 5000 puntos por hora o 10 000 puntos por hora si la app es propiedad de una organización GitHub Enterprise Cloud. Esto solo se aplica cuando la app usa su id. de cliente y secreto de cliente para solicitar datos públicos. El límite de volumen para tokens de acceso de OAuth generados por una OAuth app vienen definidos por los límites de volumen principales de los usuarios.
  • Para GITHUB_TOKEN en flujos de trabajo GitHub Actions: 1000 puntos por hora por repositorio. Para las solicitudes a los recursos que pertenecen a una cuenta de empresa en GitHub.com, el límite es de 15 000 puntos por hora por repositorio.

Puede comprobar el valor de punto de una consulta o calcular el valor de punto esperado, tal como se describe en las secciones siguientes. Las fórmulas para calcular puntos y el límite de volumen están sujetas a cambios.

Comprobación del estado de su límite de volumen principal

Puede usar los encabezados que se envían con cada respuesta para determinar el estado actual del límite de volumen principal.

Nombre de encabezadoDescripción
x-ratelimit-limitCantidad máxima de puntos que puede usar por hora.
x-ratelimit-remainingCantidad de puntos que quedan en la ventana de límite de volumen actual.
x-ratelimit-usedCantidad de puntos que ha usado en la ventana de límite de volumen actual.
x-ratelimit-resetHora a la que se restablece la ventana de límite de volumen actual en segundos de época UTC.
x-ratelimit-resourceRecurso de límite de volumen respecto al que se cuenta la solicitud. En el caso de las solicitudes de GraphQL, siempre será graphql.

También puede realizar una consulta del objeto rateLimit para comprobar su límite de volumen. Cuando sea posible, debe usar los encabezados de respuesta de límite de volumen en lugar de consultar la API para comprobar el límite de volumen.

query {
  viewer {
    login
  }
  rateLimit {
    limit
    remaining
    used
    resetAt
  }
}
CampoDescripción
limitCantidad máxima de puntos que puede usar por hora.
remainingCantidad de puntos que quedan en la ventana de límite de volumen actual.
usedCantidad de puntos que ha usado en la ventana de límite de volumen actual.
resetAtHora a la que se restablece la ventana de límite de volumen actual en segundos de época UTC.

Devolución del valor de punto de una consulta

Puede devolver el valor de punto de una consulta consultando el campo cost en el objeto rateLimit:

query {
  viewer {
    login
  }
  rateLimit {
    cost
  }
}

Predicción del valor de punto de una consulta

También puede calcular de forma aproximada el valor de punto de una consulta antes de realizar la consulta.

  1. Agrega la cantidad de solicitudes requeridas para completar cada conexión única en la llamada. Suponga que todas las solicitudes alcanzarán los límites de argumentos first o last.
  2. Divida la cantidad entre 100 y redondee el resultado al número entero más próximo para obtener el valor de punto final agregado. Este paso normaliza las cantidades grandes.

Nota: El valor mínimo de punto de una llamada a GraphQL API es 1.

Aquí se muestra una consulta y cálculo de puntaje de ejemplo:

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Esta consulta requiere de 5,101 solicitudes para completarse:

  • Aunque se devuelven 100 repositorios, la API se tiene que conectarse a la cuenta del visor una vez para obtener la lista de repositorios. Por lo tanto, las solicitudes de repositorios = 1
  • Aunque se devuelven 50 incidencias, la API tiene que conectarse a cada uno de los 100 repositorios para obtener la lista de problemas. Por lo tanto, solicitudes de problemas = 100
  • Aunque se devuelven 60 etiquetas, la API tiene que conectarse a cada uno de los 5000 problemas potenciales totales para obtener la lista de etiquetas. Por lo tanto, solicitudes de etiquetas = 5000
  • Total = 5101

Si lo dividimos entre 100 y lo redondeamos, obtenemos la puntuación final de la consulta: 51.

Límites de tasa secundarios

Además de los límites de volumen principales, GitHub aplica límites de volumen secundarios para evitar el abuso y mantener la API disponible para todos los usuarios.

Puedes encontrar un límite de volumen secundario si:

  • Haces demasiadas solicitudes simultáneas. No se permiten más de 100 solicitudes simultáneas. Este límite se comparte entre la API de REST y la API de GraphQL.
  • Haces demasiadas solicitudes a un único punto de conexión por minuto. No se permiten más de 900 puntos por minuto para los puntos de conexión de la API de REST y no se permiten más de 2000 puntos por minuto para el punto de conexión de la API de GraphQL. Para obtener más información sobre los puntos, consulta “Cálculo de puntos para el límite de volumen secundario”.
  • Haces demasiadas solicitudes por minuto. No se permiten más de 90 segundos de tiempo de CPU por 60 segundos de tiempo real. No más de 60 segundos de este tiempo de CPU puede ser para la API de GraphQL. Puedes calcular aproximadamente el tiempo de CPU midiendo el tiempo de respuesta total de las solicitudes de API.
  • Creas demasiado contenido en GitHub en un corto período de tiempo. En general, no se permiten más de 80 solicitudes de generación de contenido por minuto y no se permiten más de 500 solicitudes de generación de contenido por hora. Algunos puntos de conexión tienen límites de creación de contenido inferiores. Entre los límites de creación de contenido se incluyen las acciones realizadas en la interfaz web de GitHub, así como a través de la API de REST y la API de GraphQL.

Estos límites de volumen secundarios están sujetos a cambios sin previo aviso. También puedes encontrar un límite de volumen secundario por motivos no revelados.

Cálculo de puntos para el límite de volumen secundario

Algunos límites de volumen secundarios vienen determinados por los valores de punto de las solicitudes. En el caso de solicitudes de GraphQL, estos valores de punto son independientes de los cálculos de valor de punto para el límite de volumen principal.

SolicitarPuntos
Solicitudes de GraphQL sin mutaciones1
Solicitudes de GraphQL con mutaciones5
La mayoría de las solicitudes de la API de REST GET, HEAD y OPTIONS1
La mayoría de las solicitudes de la API de REST POST, PATCH, PUT o DELETE5

Algunos puntos de conexión de la API de REST tienen un coste de punto diferente que no se comparte públicamente.

Superación del límite de frecuencia

Si supera el límite de volumen principal, el estado de la respuesta seguirá siendo 200, pero recibirá un mensaje de error y el valor del encabezado x-ratelimit-remaining será 0. No debes reintentar la solicitud hasta después de la hora especificada por el encabezado x-ratelimit-reset.

Si supera una limitación de volumen secundaria, el estado de respuesta será 200 o 403 y recibirá un mensaje de error que indicará que ha alcanzado un límite de volumen secundaria. Si el encabezado de respuesta retry-after está presente, no debes reintentar la solicitud hasta que hayan transcurrido los segundos indicados. Si el encabezado de x-ratelimit-remaining es 0, no debes reintentar la solicitud hasta después de la hora, en segundos de época UTC, especificados por el encabezado de x-ratelimit-reset. 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.

Cumplimiento del límite de volumen

Para evitar superar un límite de volumen, debe pausar al menos 1 segundo entre solicitudes mutativas y evitar solicitudes simultáneas.

También debe suscribirse a eventos de webhook en lugar de sondear la API para obtener datos. Para obtener más información, vea «Documentación de webhooks».

También puedes transmitir el registro de auditoría para ver las solicitudes de API. Esto puede ayudarte a solucionar problemas de integraciones que superan el límite de volumen. Para obtener más información, vea «Streaming del registro de auditoría de su empresa».