Manejo de errores

Formato de las respuestas de error

Cuando una solicitud falla, la API responde con un código de estado HTTP de error y un cuerpo JSON con success: false. El objeto error contiene un code numérico, un type legible por máquinas y un mensaje info legible por personas:

{
  "success": false,
  "error": {
    "code": 101,
    "type": "no_api_key",
    "info": "User did not supply an API Key"
  }
}

Basa tu lógica en code o type, no en el texto de info, que puede cambiar. Los códigos son los mismos que en versiones anteriores de MetalAPI, así que las integraciones existentes siguen funcionando.

Errores de autenticación y de cuenta

• 101 no_api_key (401): la solicitud no incluye ninguna clave API.
• 102 invalid_api_key (401): la clave es desconocida o ha sido revocada.
• 103 account_inactive (403): la cuenta no está activa. Contacta con el soporte.
• 107 origin_not_allowed (403): se usó una clave restringida por dominio desde un sitio web que no está en su lista de dominios permitidos.

Errores de límites y de plan

• 104 too_many_requests (429): se alcanzó el límite por minuto. Espera el número de segundos indicado en la cabecera Retry-After.
• 105 quota_exceeded (429): la cuota mensual está agotada hasta el día 1 del mes siguiente (UTC).
• 106 plan_restriction (403): el endpoint o el parámetro no está incluido en tu plan, como /carat en Free o XAU-BID por debajo de Standard.

Errores de validación

Devuelven el código de estado HTTP 400 y significan que hay que corregir la propia solicitud:

• 201 invalid_base: símbolo base desconocido.
• 202 invalid_from y 203 invalid_to: símbolo from o to desconocido en /convert.
• 204 invalid_amount: falta amount o no es un número.
• 205 invalid_date: fecha con formato incorrecto o fecha futura.
• 206 invalid_timeframe: falta start_date o end_date, o el inicio es posterior al final.
• 207 timeframe_too_long: el rango es más largo de lo que permite tu plan (30 días en Free, 365 en los planes de pago).
• 208 invalid_symbols: no existe ninguno de los símbolos solicitados.
• 209 invalid_unit: unit no admitida.
• 210 invalid_carat: quilate no admitido.

En currencies, los símbolos desconocidos se omiten siempre que al menos un símbolo sea válido.

Otros errores

• 300 no_results (404): la consulta es válida pero no hay datos, por ejemplo, una fecha anterior al inicio del historial de un símbolo.
• 404 invalid_function (404): endpoint desconocido. Revisa la URL.
• 500 server_error (500): un error inesperado por nuestra parte.
• 503 service_unavailable (503): los datos de precios no están disponibles temporalmente.

Gestionar los errores en el código

Comprueba success en cada respuesta y convierte los fallos en errores que tu código pueda inspeccionar. Esta función auxiliar también gestiona las respuestas que no son JSON procedentes de proxies:

async function metalapi(path, params = {}) {
  const url = new URL(`https://metalapi.com/api/v1/${path}`);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);

  const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
  const data = await res.json().catch(() => ({
    success: false,
    error: { code: res.status, type: "http_error", info: res.statusText },
  }));

  if (!data.success) {
    const err = new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
    err.code = data.error.code;
    err.retryAfter = Number(res.headers.get("Retry-After")) || undefined;
    throw err;
  }
  return data;
}

Estrategia de reintentos

Reintenta solo los errores que pueden tener éxito en un segundo intento:

• 104: espera Retry-After segundos y vuelve a intentarlo.
• 500, 503 y errores de red: reintenta con backoff exponencial (1 s, 2 s, 4 s) y desiste después de tres reintentos.
• Todo lo demás (101 a 103, 105 a 107, los códigos de validación 2xx, 300, 404): no lo reintentes. Corrige la solicitud, la clave o el plan.

Reintentar los errores 104 y 5xx no cuesta nada, porque esas solicitudes fallidas no se facturan.

async function withRetry(fn, retries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err.code === undefined || err.code === 104 || err.code >= 500;
      if (!retryable || attempt >= retries) throw err;
      const delay = err.retryAfter ? err.retryAfter * 1000 : 1000 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

const data = await withRetry(() => metalapi("latest", { currencies: "XAU,XAG" }));