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 30 peticiones/minuto, 100/hora y 1.000/mes por IP, 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_symbolcurl "https://api.goldprice.dev/v1/prices?symbol=XAU"# correctocurl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

El spot de plata es XAG-USD-SPOT y el de cobre es HG-USD-SPOT. El spot de oro, plata y cobre está en todos los planes. Los nuevos planes no incluyen futuros. Omitir symbol devuelve las filas permitidas por defecto para tu nivel.

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

Cada respuesta lleva X-RateLimit-Remaining. Léela y reduce la velocidad antes de llegar a cero. Los límites por minuto son Free 10, Basic 60, Plus 120 y Pro 300. Una caché breve reduce las llamadas.

"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 navegadorconst 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();

Si el objetivo es simplemente mostrar un precio en vivo en lugar de procesar el JSON, usa el widget gratuito de precio del oro. Su iframe alojado no necesita clave de API y evita por completo el problema de CORS del navegador.

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

La respuesta por defecto incluye price, computed_at e is_stale. bid/ask son opcionales, solo de pago y requieren una cotización coherente de ambos lados. Todo lo demás es opcional vía ?include=: ?include=sources añade un array sources[], ?include=karat añade un desglose por quilate y gramo, y ?include=stats (solo autenticado) añade open_price, high_price, low_price, prev_close_price, los campos de variación, y divergence_bps / divergence_flag. ?include=all devuelve todo lo que tu nivel de autenticación permite. 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[] (con ?include=sources), una fila por fuente upstream, cada una con su propio price y timestamp. Cuando las fuentes no coinciden, divergence_bps (con ?include=stats) 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 Plus 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 con 15 minutos de retraso y un indicador de obsolescencia. Añade ?include=sources para las fuentes contribuyentes. 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.