Errores y troubleshooting

La API usa códigos HTTP estándar y siempre devuelve un cuerpo JSON con la misma forma cuando hay error.

Formato del error

{
  "error": {
    "code": "string",     // estable, machine-readable
    "message": "string"   // legible para humanos
  }
}

El campo code es estable: si tu integración ramifica por error, basa la lógica en code, no en message (que puede cambiar de fraseo entre versiones).

Códigos HTTP que verás

Códigos code que devuelve la API

Autenticación y permisos

Request y recursos

Estrategia de reintentos recomendada

Las únicas categorías que conviene reintentar automáticamente son 429 (rate limit, esperando Retry-After) y 5xx (fallo transitorio). Para todo lo demás, reintentar solo amplifica el problema.

async function rud1Get(path, attempt = 0) {
  const res = await fetch(`https://www.rud1.es${path}`, {
    headers: { Authorization: `Bearer ${process.env.RUD1_API_KEY}` },
  });

  // 429: espera el Retry-After del servidor
  if (res.status === 429 && attempt < 3) {
    const retry = Number(res.headers.get("Retry-After") ?? 1) * 1000;
    await new Promise((r) => setTimeout(r, retry));
    return rud1Get(path, attempt + 1);
  }

  // 5xx: backoff exponencial con jitter — máximo 3 intentos
  if (res.status >= 500 && attempt < 3) {
    const wait = (2 ** attempt) * 500 + Math.random() * 250;
    await new Promise((r) => setTimeout(r, wait));
    return rud1Get(path, attempt + 1);
  }

  // 4xx ≠ 429: error del cliente, no reintentar
  if (!res.ok) {
    const body = await res.json();
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }
  return res.json();
}

Diagnóstico rápido

Estoy recibiendo 401 todo el rato

• Verifica que el header sea exactamente Authorization: Bearer rud1_sk_... con un espacio entre "Bearer" y el token.
• Comprueba que la clave no esté revocada en Ajustes → Claves API.
• Si configuraste expiración, mira si ya pasó. La columna Expira del listado lo indica.
• Asegúrate de que copiaste el secreto completo (incluye el guion bajo entre el prefijo y la parte aleatoria).

Recibo 403 insufficient_scope

El endpoint que intentas usar requiere un scope que tu clave no tiene. El campo message te dirá cuál falta. Crea una clave nueva con esos scopes o, si la integración solo necesita ese permiso ocasional, considera dividirla en dos claves distintas (una por privilegio).

404 cuando estoy seguro de que el recurso existe

Por seguridad nunca diferenciamos "no existe" de "existe pero pertenece a otra organización": ambos casos devuelven 404. Verifica que la clave que estás usando es de la misma organización a la que pertenece el recurso.

Reportar un problema

Si crees que has encontrado un comportamiento incorrecto, escribe a support@rud1.es con:

• El prefijo de la clave (solo los 16 primeros caracteres, rud1_sk_...).
• El método y la ruta exacta de la petición.
• La fecha y hora aproximada (UTC) en la que pasó — facilita encontrar el log.
• El cuerpo de error completo que recibiste.