Errores y rate limits

Programa contra el campo code, no contra el texto de error: el code es estable, el mensaje puede venir redactado por la fuente oficial y cambiar.

Un 404 quiere decir que la fuente oficial sí respondió, y respondió que no hay datos para esa combinación. El caso más común es un dígito equivocado en el documento: la fuente contesta que no corresponde a un propietario activo del vehículo.

Por eso el 404 no se reintenta: el resultado sería idéntico. Distinguirlo del 502 te evita bucles de reintento sobre consultas que nunca van a devolver datos.

El cuerpo trae dos campos para que no tengas que adivinar la factura: charged dice si esta consulta descontó crédito, y freeNoResultsLeft, cuántas consultas sin resultado gratis te quedan este mes de ese mismo code — cada código lleva su propia cuota.

HTTP 404
{
  "error": "El documento enviado no corresponde a un propietario
            activo de esa placa.",
  "code": "propietario_no_coincide",
  "charged": false,
  "freeNoResultsLeft": 7
}

Se descuenta 1 crédito cuando la consulta devuelve datos (el objeto data presente, con mode: "live"). Un 502 nunca cobra: ahí la fuente no respondió y no hay consulta que facturar.

Repetir la misma consulta no vuelve a cobrar. Guardamos en caché el resultado de cada consulta (misma placa y documento). Si repites dentro de la ventana de caché, respondemos al instante desde caché — la respuesta trae fromCache: true — y no se descuenta crédito: solo cobra la primera consulta viva. La ventana depende del dato: los datos del vehículo se guardan 24 horas, y las demás fuentes van de horas a 30 días. Usa refresh: true si necesitas forzar una consulta viva.

Consultas sin resultado (404): 10 gratis cada mes por cada code. Pasadas esas 10, ese 404 cuesta lo mismo que una consulta con datos: la fuente se consultó igual y respondió. Las cuotas son independientes: propietario_no_coincide, vehiculo_no_registrado y consulta_sin_resultado llevan cada uno sus 10, así que agotar una no empieza a cobrarte las otras. El contador es por cuenta, se reinicia el primer día de cada mes (hora de Colombia) y cada respuesta trae el de su propio código en freeNoResultsLeft.

Repetir una consulta que ya salió sin resultado no cobra nunca, ni siquiera con la cortesía agotada: la guardamos 3 meses y te la devolvemos desde caché con fromCache: true y charged: false. Solo cuesta preguntar algo nuevo. Si necesitas verificar de nuevo contra la fuente —por ejemplo si crees que el vehículo ya se matriculó—, usa refresh: true: esa sí es una consulta viva y puede cobrar.

Excepción: consulta-full siempre cobra sus 2 créditos, incluso desde caché: combina varias fuentes con vigencias distintas y no expone un único fromCache. Para pruebas repetidas de la misma placa te sale más barato usar los endpoints individuales.

El límite es de 1.000 consultas por minuto por API key. Va por key y no por IP, así que puedes integrar desde un backend con una sola IP de salida sin que tus usuarios compartan cuota.

Ante un 429, aplica backoff exponencial (1s, 2s, 4s) con un tope de reintentos y respeta el header Retry-After, que trae los segundos que faltan. Ante un 502, la fuente oficial no respondió: reintenta más tarde. Ante un 4xx, no reintentes — corrige los datos. Si necesitas más volumen, escríbenos.

Ver autenticación y la documentación.

CORS no está habilitado. Ninguna respuesta nuestra incluye el header Access-Control-Allow-Origin, así que un fetch desde el JavaScript de una página la bloquea el navegador. La API es servidor a servidor.

Ese fallo no es uno de los códigos de esta página. No verás code ni cuerpo JSON: el navegador descarta la respuesta antes de entregártela y en la consola queda un TypeError: Failed to fetch con la nota de bloqueo por política de mismo origen. No lo reintentes: reintentar desde el navegador da siempre lo mismo.

El motivo es de seguridad: llamar desde el navegador obliga a mandar la API key en el código que descarga el visitante, y ahí la lee cualquiera que abra las herramientas de desarrollo — con ella consumiría tus créditos. Llama desde tu backend con la key en una variable de entorno y expón tu propio endpoint a tu frontend. Más detalle en autenticación y CORS.