Maneja errores de API

La API de Calendar 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 las APIs de Cloud se explica bien la retirada exponencial y cómo usarla con las APIs de Google APIs.

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. Esto puede significar que no se proporcionó un campo o parámetro obligatorio, que el valor proporcionado no es válido o que la combinación de campos proporcionados no es 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 en consecuencia.

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 ves esto 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 Developer Console.

{
 "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 Google 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 Actualmente, son funcionalmente similares y se debe responder de la misma manera, usando la retirada exponencial. Además, asegúrate de que tu app siga las prácticas recomendadas de administrar cuotas.

403: Calendar usage limits exceeded

El usuario alcanzó uno de los límites de Google 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. El organizador solo 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 la llamada al método de actualización.

409: Conflict

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: Excluye todos los elementos por lotes que se completaron correctamente y todos los que definitivamente fallaron, y vuelve a intentar los restantes en una operación events.batch diferente o en 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 almacén 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

El etag proporcionado en el encabezado If-match ya no corresponde al 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 recuperar 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 Actualmente, son funcionalmente similares y se debe responder de la misma manera, usando la retirada exponencial. Además, asegúrate de que tu app siga las prácticas recomendadas de administrar 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.