Maneja errores de API

La API de Calendario de Google muestra dos niveles de información de errores:

  • Mensajes y códigos de error HTTP en el encabezado
  • Un objeto JSON en el cuerpo de la respuesta con detalles adicionales que pueden ayudarte a determinar cómo controlar el error

En el resto de esta página, se proporciona una referencia de los errores de Calendar, con algunas instrucciones para controlarlos en tu app.

Implementa la retirada exponencial

En la documentación de Google Cloud Storage , se explica la retirada exponencial y cómo usarla con las APIs de Google.

Errores y acciones sugeridas

En esta sección, se proporciona la representación JSON completa de cada error que se muestra y las acciones sugeridas que puedes realizar para controlarlo.

400: Bad Request

Error de los usuarios. Este error se produce cuando no proporcionas un campo o parámetro obligatorio, proporcionas un valor no válido o proporcionas una combinación de campos no válida.

{
  "error": {
    "errors": [
      {
        "domain": "calendar",
        "reason": "timeRangeEmpty",
        "message": "The specified time range is empty.",
        "locationType": "parameter",
        "location": "timeMax"
      }
    ],
    "code": 400,
    "message": "The specified time range is empty."
  }
}

Acción sugerida: Como se trata de un error permanente, no vuelvas a intentarlo. En su lugar, lee el mensaje de error y cambia tu solicitud según corresponda.

401: Invalid Credentials

Encabezado de autorización no válido. El token de acceso que usas venció o no es válido.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization"
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

Acciones sugeridas:

  • Obtén un token de acceso nuevo con el token de actualización de larga duración.
  • Si esto falla, dirige al usuario a través del flujo de OAuth, como se describe en Autoriza solicitudes con OAuth 2.0.
  • Si se produce este error para una cuenta de servicio, verifica que hayas completado correctamente todos los pasos en la página de la cuenta de servicio.

403: User Rate Limit Exceeded

Se alcanzó uno de los límites de la consola de Google Cloud.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "userRateLimitExceeded",
        "message": "User Rate Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "User Rate Limit Exceeded"
  }
}

Acciones sugeridas:

403: Rate Limit Exceeded

El usuario alcanzó la tasa máxima de solicitudes de la API de Calendar por calendario o por usuario autenticado.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Rate Limit Exceeded"
  }
}

Acción sugerida: rateLimitExceeded errores pueden mostrar códigos de error 403 o 429 Son funcionalmente similares y debes controlarlos de la misma manera, con la retirada exponencial. Además, asegúrate de que tu app siga las prácticas recomendadas de la administración de cuotas.

403: Calendar usage limits exceeded

El usuario alcanzó uno de los límites de Calendar establecidos para proteger a los usuarios y la infraestructura de Google de comportamientos abusivos.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "message": "Calendar usage limits exceeded.",
        "reason": "quotaExceeded"
      }
    ],
    "code": 403,
    "message": "Calendar usage limits exceeded."
  }
}

Acciones sugeridas:

403: Forbidden for non-organizer

La solicitud de actualización del evento intenta establecer una de las propiedades del evento compartido en una copia que no es del organizador. Solo el organizador puede establecer propiedades compartidas (por ejemplo, guestsCanInviteOthers, guestsCanModify o guestsCanSeeOtherGuests).

{
  "error": {
    "errors": [
      {
        "domain": "calendar",
        "reason": "forbiddenForNonOrganizer",
        "message": "Shared properties can only be changed by the organizer of the event."
      }
    ],
    "code": 403,
    "message": "Shared properties can only be changed by the organizer of the event."
  }
}

Acciones sugeridas:

  • Si usas Events: insert, Events: import o Events: update, y tu solicitud no incluye ninguna propiedad compartida, esto equivale a intentar establecerlas en sus valores predeterminados. Considera usar Events: patch en su lugar.
  • Si tu solicitud tiene propiedades compartidas, asegúrate de intentar cambiar estas propiedades solo si actualizas la copia del organizador.

404: Not Found

No se encontró el recurso especificado. Esto puede suceder en varios casos. Estos son algunos ejemplos:

  • Cuando el recurso solicitado (con el ID proporcionado) nunca existió.
  • Cuando se accede a un calendario al que el usuario no puede acceder.
{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found"
      }
    ],
    "code": 404,
    "message": "Not Found"
  }
}

Acción sugerida: Usa la retirada exponencial.

409: The requested identifier already exists

Ya existe una instancia con el ID determinado en el almacenamiento.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "duplicate",
        "message": "The requested identifier already exists."
      }
    ],
    "code": 409,
    "message": "The requested identifier already exists."
  }
}

Acción sugerida: Genera un ID nuevo si deseas crear una instancia nueva; de lo contrario, usa el events.update método.

409: Conflicto

No se puede ejecutar un elemento por lotes dentro de una events.batch operación debido a un conflicto operativo con otros elementos por lotes solicitados.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "conflict",
        "message": "Conflict"
      }
    ],
    "code": 409,
    "message": "Conflict"
  }
}

Acción sugerida: Quita los elementos completados y con errores, y vuelve a intentar con los elementos restantes en una operación events.batch diferente o en las operaciones de eventos individuales correspondientes.

410: Gone

Los parámetros syncToken o updatedMin ya no son válidos. Este error también puede ocurrir si una solicitud intenta borrar un evento que ya se borró.

{
  "error": {
    "errors": [
      {
        "domain": "calendar",
        "reason": "fullSyncRequired",
        "message": "Sync token is no longer valid, a full sync is required.",
        "locationType": "parameter",
        "location": "syncToken"
      }
    ],
    "code": 410,
    "message": "Sync token is no longer valid, a full sync is required."
  }
}

o

{
  "error": {
    "errors": [
      {
        "domain": "calendar",
        "reason": "updatedMinTooLongAgo",
        "message": "The requested minimum modification time lies too far in the past.",
        "locationType": "parameter",
        "location": "updatedMin"
      }
    ],
    "code": 410,
    "message": "The requested minimum modification time lies too far in the past."
  }
}

o

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "deleted",
        "message": "Resource has been deleted"
      }
    ],
    "code": 410,
    "message": "Resource has been deleted"
  }
}

Acción sugerida: Para los parámetros syncToken o updatedMin, borra el almacenamiento y vuelve a sincronizar. Para obtener más detalles, consulta Sincroniza recursos de manera eficiente. Para los eventos ya borrados, no es necesario realizar ninguna otra acción.

412: Precondition Failed

La ETag proporcionada en el encabezado If-Match ya no corresponde a la ETag actual del recurso.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "conditionNotMet",
        "message": "Precondition Failed",
        "locationType": "header",
        "location": "If-Match"
      }
    ],
    "code": 412,
    "message": "Precondition Failed"
  }
}

Acción sugerida: Vuelve a obtener la entidad y vuelve a aplicar los cambios. Para obtener más detalles, consulta Obtén versiones específicas de los recursos.

429: Too many requests

Se produce un error rateLimitExceeded cuando el usuario envió demasiadas solicitudes en un período determinado.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 429,
    "message": "Rate Limit Exceeded"
  }
}

Acción sugerida: rateLimitExceeded errores pueden mostrar códigos de error 403 o 429 Son funcionalmente similares y debes controlarlos de la misma manera, con la retirada exponencial. Además, asegúrate de que tu app siga las prácticas recomendadas de la administración de cuotas.

500: Backend Error

Se produjo un error inesperado mientras se procesaba la solicitud.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "backendError",
        "message": "Backend Error"
      }
    ],
    "code": 500,
    "message": "Backend Error"
  }
}

Acción sugerida: Usa la retirada exponencial.