Errores
Los códigos de error de la API de Turbodato (400, 401, 403, 429 y 500), la forma del cuerpo y cuáles conviene reintentar.
Todos los errores llegan como JSON con una clave error. El status HTTP es el contrato; el
texto del mensaje puede cambiar, así que no armes lógica sobre él.
| Status | Qué pasó | Qué hacer |
|---|---|---|
400 | Falta clientId y tu key alcanza más de un tablero (o ninguno). | Pedí /clients y mandá el que corresponda. |
401 | La key falta, no existe o fue revocada. | Revisá el header X-API-Key. Si la revocaron, creá otra. |
403 | El clientId no es uno de tus tableros, o el tablero no tiene activo lo que pediste (es el caso de /price-control sin Control de PVP). | No reintentes: la respuesta no va a cambiar sola. |
429 | Pasaste las llamadas por minuto de tu key. | Esperá lo que dice Retry-After y reintentá. Ver límites. |
500 | Algo se rompió de nuestro lado. | Reintentá con backoff. Si sigue, pasanos el ref. |
Forma del cuerpo
{ "error": "Missing clientId query parameter" }{ "error": "Internal error", "ref": "a3f19c2b" }Un 500 nunca trae el detalle técnico: no te serviría para nada y expondría cómo está armado el
sistema por dentro. A cambio trae ref, la misma referencia que quedó en nuestro registro.
Escribinos "me dio un 500 con ref a3f19c2b" y lo encontramos al toque, sin tener que adivinar
por el horario.
Qué reintentar
En un 429, esperá lo que dice Retry-After. En un 500, backoff exponencial: 2, 4, 8
segundos, y cortá después de cuatro o cinco intentos. Todos los endpoints son GET e
idempotentes, así que reintentar nunca duplica nada.
El pedido está mal armado o la credencial no alcanza. Repetirlo da la misma respuesta y te gasta cupo. Corregí el pedido o la key.
Respuestas vacías que no son errores
Algunas respuestas llegan con 200 y sin datos. No son fallas, y conviene distinguirlas:
- Un día sin relevamiento. Pedir con
dateun día en que no se relevó tu catálogo devuelve productos sin ofertas. Dice que ese día no hubo datos. - Un filtro que no matchea.
brand=Samsdevuelve cero productos, no un error:brandes coincidencia exacta. Los valores válidos salen de/filters. - Un parámetro mal escrito. Un parámetro que la API no conoce se ignora en silencio:
orderBy=priceASCdevuelve el orden por nombre. - Cuotas vacías.
installments: []puede ser que el sitio no publique cuotas o que todavía no se hayan relevado. Las dos llegan igual.
Límites de uso
La API de Turbodato admite 60 llamadas por minuto por key. Qué headers informan el cupo, qué pasa con un 429 y cómo paginar sin gastar de más.
Recetas
Integraciones completas con la API de Turbodato. Productos en rojo a Google Sheets, sincronizar sólo si hay datos nuevos, alertas de PVP y carga a un BI.