API de precio del oro en Stack Overflow: errores de desarrolladores, resueltos

Cuando una integración falla, los desarrolladores pegan el error en Stack Overflow. Las preguntas que aparecen para una API de precio del oro son casi siempre las mismas: un rechazo de autenticación, un símbolo mal formado, un tope de límite de tasa o un error CORS desde el navegador. Este artículo resuelve cada uno directamente, usando goldprice.dev como ejemplo práctico. Cada fragmento de código a continuación es una llamada real y funcional contra https://api.goldprice.dev.

"401 Unauthorized" — mi clave API es rechazada

La clave va en la cabecera Authorization como token bearer, y la palabra Bearer (con un espacio al final) tiene que estar presente:

curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT \
  -H "Authorization: Bearer ga_live_YOUR_KEY"

Las tres cosas que realmente causan un 401: falta el prefijo Bearer , la clave tiene un salto de línea o comilla de un copia-pega, o la clave se lee desde una variable de entorno que no está cargada. Las claves tienen el prefijo ga_live_. No es estrictamente necesario tener una clave para empezar — las llamadas anónimas funcionan, pero están limitadas a 100 peticiones por hora por IP y devuelven una respuesta reducida, así que para cualquier uso más allá de una prueba rápida, autentícate.

"400 invalid_symbol" — el error más común al empezar

El parámetro symbol no es un código de metal sin más. Es BASE-QUOTE-CONTRACT. Pasar symbol=XAU devuelve 400 invalid_symbol; el valor correcto para el spot de oro en vivo es XAU-USD-SPOT:

# incorrecto — 400 invalid_symbol
curl "https://api.goldprice.dev/v1/prices?symbol=XAU"

# correcto
curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

El spot de plata es XAG-USD-SPOT y el cobre es HG-USD-SPOT. Los futuros usan el contrato FUTURES, por ejemplo XAU-USD-FUTURES — ten en cuenta que los futuros de oro requieren el nivel Basic, y la plata y el cobre requieren Pro, así que en el nivel gratuito esos símbolos devuelven 403 plan_gated. Omitir symbol por completo devuelve las filas permitidas por defecto para tu nivel, lo que también es una forma válida de evitar el error.

"429 Too Many Requests" — gestión de límites de tasa

Cada respuesta lleva una cabecera X-RateLimit-Remaining. Léela y reduce la velocidad antes de llegar a cero, en lugar de hacer polling ciego y recibir 429s. El plan gratuito es de 30 peticiones por minuto; Basic es 120; Pro y Realtime son 500. Para la mayoría de las aplicaciones, una caché del lado del cliente de corta duración, ajustada a la frecuencia real de cambio del precio, te mantiene bien por debajo del límite — el precio spot no cambia significativamente cada segundo, así que cachear unos pocos segundos es generalmente correcto.

"Error CORS" — llamar a la API desde el navegador

No llames a la API directamente desde JavaScript en el frontend con tu clave. Dos razones: expone ga_live_... a cualquiera que abra las herramientas de desarrollador, y el CORS del navegador lo bloqueará. Haz un proxy de la llamada a través de tu propio backend, mantén la clave en el servidor, y haz que el navegador llame a tu endpoint:

// tu ruta de backend — la clave nunca llega al navegador
const r = await fetch(
  "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT",
  { headers: { Authorization: `Bearer ${process.env.GOLDPRICE_API_KEY}` } },
);
const data = await r.json();

"¿Cuál campo es el precio?" — leer la respuesta

La respuesta anónima te da price, bid, ask, computed_at, is_stale, un array sources[] y un desglose por quilate y gramo. Autentícate y la estructura añade open_price, high_price, low_price, prev_close_price, los campos de variación, y divergence_bps / divergence_flag. Dos campos son clave para la exactitud:

• is_stale — true cuando el valor es más antiguo que su ventana de actualización esperada. Compruébalo antes de mostrar un precio.
• sources[] — una fila por fuente upstream, cada una con su propio price y timestamp. Cuando las fuentes no coinciden, divergence_bps te dice cuánto, para que puedas definir tu propia tolerancia en lugar de confiar en un número combinado.

"¿Cómo obtengo datos históricos / OHLC?"

El historial de cierres diarios está en GET /v1/prices/history, disponible en todos los niveles — lo que cambia es hasta dónde puedes retroceder. El nivel gratuito devuelve los últimos 30 días, Basic el último año, y Pro el historial completo. Así que si una consulta histórica devuelve menos de lo esperado, es la ventana de tu nivel, no un error de autenticación.

La llamada más corta que funciona

Sin clave, símbolo correcto:

curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

Eso devuelve un precio del oro en vivo y honesto con sus fuentes y un indicador de obsolescencia. Cuando quieras la respuesta completa y límites más altos, una clave gratuita tarda un minuto. Si prefieres un recorrido específico por lenguaje, Fetch live gold prices in JavaScript cubre el camino REST de extremo a extremo, y Caching gold prices and staying inside rate limits cubre cómo hacerlo a escala.