Errores y rate limits

Programa contra el campo code, no contra el texto de error: el code es estable y el texto puede cambiar sin aviso.

Algunos endpoints mandan además errorCode con el mismo valor. Es un alias que se conserva por compatibilidad: usa code.

Un 404 quiere decir que la consulta sí se hizo, y la respuesta es que no hay datos para esa combinación. El caso más común es un dígito equivocado en el documento: 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
}

Cada endpoint cobra su precio en créditos cuando la consulta devuelve datos (el objeto data presente, con mode: "live"). La mayoría cuesta 1 crédito; algunos cuestan 2 o 3, y el precio está en la documentación de cada endpoint. /api/licencia cobra 1 crédito más cuando no envías primerApellido y lo resolvemos nosotros. Un 5xx nunca cobra: ahí no pudimos consultar y no hay nada 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. Aplica a los endpoints de vehículo por placa y documento (consulta, consulta-full, vehiculo-basico, apto-traspaso), a consulta-por-vin, licencia y catalogo; en los demás endpoints un 404 no cobra nunca. Pasadas esas 10, ese 404 cuesta lo mismo que una consulta con datos: la consulta se hizo igual y tuvo respuesta. 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 durante 24 horas, ni siquiera con la cortesía agotada: la guardamos 24 horas y te la devolvemos desde caché con fromCache: true y charged: false. Pasado ese plazo se vuelve a consultar, por si el dato cambió. Si necesitas verificar de nuevo —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 3 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. Lo mismo con un 503 fuente_saturada: ese cupo no depende de tu cuenta, y el Retry-After puede ser de segundos o de horas — reintentar antes vuelve a chocar con el mismo contador. Ante un 502 no pudimos consultar el dato: 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.