R2 Connect API

Errores

Forma de los errores, qué significa cada código y cómo reaccionar a cada uno.

Los errores usan códigos de estado HTTP estándar y siempre traen el mismo cuerpo JSON, con un code estable para tu lógica y un message legible para tus registros.

json

{
  "error": {
    "code": "forbidden",
    "message": "Esta API key no tiene el permiso 'read:payments'."
  }
}

Códigos#

HTTP	Código	Qué pasó	Qué hacer
`400`	`bad_request`	Un parámetro tiene formato inválido, casi siempre una fecha.	Corrige el parámetro. Reintentar igual no sirve.
`401`	`unauthorized`	Falta la llave, es inválida o fue revocada.	Detén la sincronización y pide una llave nueva al dueño.
`403`	`forbidden`	La llave es válida pero no tiene el permiso de ese recurso.	Pide al dueño una llave con el permiso, o deja de consultar ese recurso.
`404`	`not_found`	El recurso no existe en esa cuenta, o la ruta está mal escrita.	Verifica el número de orden y la ruta.
`429`	`rate_limited`	Excediste el límite de solicitudes.	Espera lo que indique `Retry-After` y reintenta.
`500`	`internal_error`	Falla del lado de R2.	Reintenta con espera creciente. Si persiste, repórtalo con el `X-Request-Id`.

Aislamiento entre negocios

Si pides un registro que existe pero pertenece a otro negocio, la respuesta es 404, no 403. Es deliberado: la API no revela ni siquiera la existencia de datos ajenos a tu llave.

Manejo recomendado#

javascript

const res = await fetch(url, { headers });

if (!res.ok) {
  const { error } = await res.json();

  switch (error.code) {
    case "unauthorized":   // llave muerta: no sirve reintentar
      await avisarAlCliente("Vuelve a conectar tu cuenta de R2");
      return;
    case "forbidden":      // falta permiso: deja de pedir este recurso
      desactivarRecurso(url);
      return;
    case "rate_limited":   // espera y reintenta
      return reintentarDespuésDe(res.headers.get("Retry-After"));
    default:
      registrar(error.code, error.message, res.headers.get("X-Request-Id"));
  }
}

AnteriorLímites de uso SiguienteCuenta