Para desarrolladores

Documentación de la API

Una API REST para que aseguradoras, CDA y transportadoras integren la flota de vehículos y conductores de su empresa con PlacaSegura: cargarla, consultar el RUNT y traer los vencimientos por código, sin pasar por el panel.

Para quién es

Cualquier empresa aprobada en PlacaSegura puede usar la API: aseguradoras que quieren traer el estado de sus asegurados, CDA que sincronizan las fechas de revisión de los vehículos que atienden, transportadoras que cargan su flota desde su propio sistema. La API hace lo mismo que el panel de la empresa (panel), pero pensada para integrarse por código.

Cómo conseguir una llave

Registra tu empresa en /empresas. Es gratis y no pide clave: te llega un enlace al correo para entrar a tu panel.
Espera la aprobación. Mientras tu empresa no esté aprobada, la API responde 403 empresa_no_aprobada con cualquier llave.
Ya aprobada, entra a la pestaña API de tu panel y crea una llave. Se muestra una sola vez: guárdala en tu sistema en ese momento, porque después solo se ve su prefijo. Puedes tener hasta 5 llaves activas a la vez, y revocar cualquiera desde ahí.

Registrar mi empresa

Autenticación

Toda petición lleva la llave en la cabecera Authorization, con el esquema Bearer:

Cabecera

Authorization: Bearer ps_live_xxxxxxxx_…

Sin llave, con una llave mal formada, inexistente o revocada: 401 no_autorizado, con la cabecera WWW-Authenticate: Bearer. Con una llave válida pero de una empresa que todavía no está aprobada, o que fue suspendida: 403 empresa_no_aprobada. Suspender una empresa corta el acceso al instante: se comprueba en cada petición, no solo al crear la llave.

Cada llave tiene su límite de 120 peticiones por minuto, y la empresa otro de 120 por minuto sumando todas sus llaves: crear más llaves no da más cupo. Desde una misma IP, después de 60 respuestas 401 en un minuto se responde 429 limite.

401 — sin llave o llave inválida

{"error": {"codigo": "no_autorizado", "mensaje": "La llave no es válida."}}

403 — empresa no aprobada o suspendida

{"error": {"codigo": "empresa_no_aprobada", "mensaje": "Tu empresa no está aprobada, o fue suspendida."}}

Formato

JSON en UTF-8, con los nombres de campo en snake_case (tipo_documento, conductor_referencia…).
Las placas se aceptan con o sin guiones (ABC-123 o ABC123) y se normalizan: siempre salen en mayúsculas y sin guiones.
Las fechas van en AAAA-MM-DD (también se aceptan en D/M/AAAA al cargarlas). El campo dias de un documento se cuenta en el calendario de Bogotá: si ya venció, sale negativo.
Toda respuesta, errores incluidos, lleva Content-Type: application/json; charset=utf-8 y Cache-Control: no-store. Las respuestas 204 van sin cuerpo.
Un error siempre tiene la forma {"error": {"codigo", "mensaje"}}; los errores de un documento dentro de una lista agregan indice.
Un método que la ruta no define (por ejemplo, un PATCH) responde 405.

Catálogo

Los mismos tipos de la tabla del catálogo, más abajo en esta página. avisos_dias son los umbrales en los que se avisa (30, 7 y 1 día antes, o 7 y 1 en los de aviso corto).

GET /api/v1/catalogo

Los tipos de documento del catálogo: a qué aplican, con cuántos días de anticipación se avisa y si llevan nombre libre.

curl

curl https://placasegura.co/api/v1/catalogo \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

Respuesta de ejemplo

[
  {
    "tipo": "SOAT",
    "nombre": "SOAT",
    "aplica_a": "vehiculo",
    "avisos_dias": [30, 7, 1],
    "norma": "Ley 769 de 2002",
    "lleva_nombre": false
  },
  {
    "tipo": "LICENCIA_CONDUCCION",
    "nombre": "Licencia de conducción",
    "aplica_a": "conductor",
    "avisos_dias": [30, 7, 1],
    "norma": "Ley 1383 de 2010, art. 22",
    "lleva_nombre": false
  },
  {
    "tipo": "OTRO",
    "nombre": "Otro",
    "aplica_a": "cualquiera",
    "avisos_dias": [30, 7, 1],
    "norma": null,
    "lleva_nombre": true
  }
  // … el resto de tipos del catálogo, en la tabla de abajo
]

200 con la lista completa.

Vehículos

En el PUT, conductor_referencia ausente conserva el conductor que ya tenía el vehículo; null o "" lo desasigna; un texto lo busca por referencia (422 si no hay un conductor con esa referencia en tu empresa). Los documentos que no vienen en la lista no se borran.

GET /api/v1/vehiculos

Todos los vehículos de tu empresa, ordenados por placa.

curl

curl https://placasegura.co/api/v1/vehiculos \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

Respuesta de ejemplo

[
  {
    "placa": "ABC123",
    "conductor": {"referencia": "C-045", "nombre": "Ana Ríos"},
    "documentos": [
      {"tipo": "SOAT", "nombre": "SOAT", "fecha": "2026-11-15", "dias": 20, "fuente": "runt"},
      {"tipo": "OTRO", "nombre": "GPS", "fecha": "2027-01-01", "dias": 67, "fuente": "api"}
    ]
  }
]

200 con la lista (puede ser []).

GET /api/v1/vehiculos/{placa}

Un vehículo por placa (con o sin guiones: se normaliza).

curl

curl https://placasegura.co/api/v1/vehiculos/ABC123 \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

Respuesta de ejemplo

{
  "placa": "ABC123",
  "conductor": {"referencia": "C-045", "nombre": "Ana Ríos"},
  "documentos": [
    {"tipo": "SOAT", "nombre": "SOAT", "fecha": "2026-11-15", "dias": 20, "fuente": "runt"}
  ]
}

200 con el vehículo · 404 no_encontrado · 422 datos_invalidos si la placa no es válida.

PUT /api/v1/vehiculos/{placa}

Crea el vehículo si no existe, o lo actualiza. Todo o nada: si un documento del arreglo falla, no se guarda nada de la petición (ni el vehículo, si era nuevo).

Cuerpo

{
  "conductor_referencia": "C-045",
  "documentos": [
    {"tipo": "SOAT", "fecha": "2026-11-15"},
    {"tipo": "OTRO", "fecha": "2027-01-01", "nombre": "GPS"}
  ]
}

curl

curl -X PUT https://placasegura.co/api/v1/vehiculos/ABC123 \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"conductor_referencia": "C-045", "documentos": [{"tipo": "SOAT", "fecha": "2026-11-15"}]}'

Respuesta de ejemplo

{
  "placa": "ABC123",
  "conductor": {"referencia": "C-045", "nombre": "Ana Ríos"},
  "documentos": [
    {"tipo": "SOAT", "nombre": "SOAT", "fecha": "2026-11-15", "dias": 20, "fuente": "api"}
  ]
}

201 si lo creó, 200 si lo actualizó, con el vehículo · 422 datos_invalidos (placa, forma del cuerpo, conductor inexistente, o documentos[i]: … con indice) · 409 tope_flota (500 vehículos, o el tope de documentos del vehículo) · 409 conflicto · 400 sin cuerpo (o con Content-Length: 0).

DELETE /api/v1/vehiculos/{placa}

Borra el vehículo y todos sus documentos.

curl

curl -X DELETE https://placasegura.co/api/v1/vehiculos/ABC123 \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

204 sin cuerpo · 404 no_encontrado.

Documentos del vehículo

{tipo} es un código del catálogo (SOAT, RTM, TODO_RIESGO…) que aplique a vehículo. OTRO necesita nombre; el resto lo ignora.

PUT /api/v1/vehiculos/{placa}/documentos/{tipo}

Crea o actualiza un documento suelto del vehículo (un cambio de fecha reinicia sus avisos).

Cuerpo

{"fecha": "2026-11-15"}

curl

curl -X PUT https://placasegura.co/api/v1/vehiculos/ABC123/documentos/SOAT \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"fecha": "2026-11-15"}'

Respuesta de ejemplo

{"tipo": "SOAT", "nombre": "SOAT", "fecha": "2026-11-15", "dias": 20, "fuente": "api"}

200 con el documento · 404 no_encontrado si el vehículo no existe · 422 datos_invalidos (tipo desconocido o de conductor, fecha inválida, falta nombre en OTRO) · 409 tope_flota si el documento es nuevo y el vehículo ya llegó a su tope de documentos.

DELETE /api/v1/vehiculos/{placa}/documentos/{tipo}

Quita un documento del vehículo. `OTRO` necesita el `nombre` con el que se guardó: en el cuerpo, o en `?nombre=` para clientes que no mandan cuerpo en un DELETE.

Cuerpo

{"nombre": "GPS"}

curl

curl -X DELETE "https://placasegura.co/api/v1/vehiculos/ABC123/documentos/OTRO?nombre=GPS" \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

204 sin cuerpo · 404 no_encontrado (el vehículo o el documento) · 422 datos_invalidos (tipo, o falta el nombre de OTRO).

RUNT del vehículo

Gasta una consulta del tope mensual de RUNT de tu empresa (ver la sección RUNT más abajo). El número de documento nunca se guarda ni se devuelve.

POST /api/v1/vehiculos/{placa}/runt

Trae del RUNT el SOAT y la tecnomecánica de la placa con el documento del propietario, y los guarda (con `fuente: "runt"`).

Cuerpo

{"tipo_documento": "NIT", "numero_documento": "900123456"}

curl

curl -X POST https://placasegura.co/api/v1/vehiculos/ABC123/runt \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"tipo_documento": "NIT", "numero_documento": "900123456"}'

Respuesta de ejemplo

{
  "documentos": [
    {"tipo": "SOAT", "fecha": "2027-03-01"},
    {"tipo": "RTM", "fecha": "2027-01-15"}
  ],
  "consultas_restantes": 29
}

200 con los documentos guardados y las consultas que te quedan · 422 datos_invalidos (tipo o número inválido) · 404 no_encontrado (la placa no es de tu empresa, o no aparece en el RUNT) · 422 documento_no_coincide (el documento no es del propietario activo) · 429 tope_runt · 429 limite · 503 runt_no_disponible.

Conductores

El PUT fusiona, no reemplaza: celular y correo ausentes conservan lo que ya tenía el conductor (como una celda vacía en un CSV); null o "" los borra. Un conductor que apagó un canal (se dio de baja de correo o de WhatsApp) lo sigue teniendo apagado aunque vuelvas a mandar ese dato.

GET /api/v1/conductores

Todos los conductores de tu empresa, ordenados por nombre.

curl

curl https://placasegura.co/api/v1/conductores \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

Respuesta de ejemplo

[
  {
    "referencia": "C-045",
    "nombre": "Ana Ríos",
    "celular": "+573001234567",
    "correo": "[email protected]",
    "dado_de_baja": false,
    "documentos": [
      {"tipo": "LICENCIA_CONDUCCION", "nombre": "Licencia de conducción", "fecha": "2030-05-01", "dias": 1313, "fuente": "runt"}
    ]
  }
]

200 con la lista (puede ser []).

GET /api/v1/conductores/{referencia}

Un conductor por su referencia (la que tú le pusiste al cargarlo: tu código interno o de nómina. No uses la cédula: la referencia viaja en la URL y PlacaSegura no guarda cédulas).

curl

curl https://placasegura.co/api/v1/conductores/C-045 \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

Respuesta de ejemplo

{
  "referencia": "C-045",
  "nombre": "Ana Ríos",
  "celular": "+573001234567",
  "correo": "[email protected]",
  "dado_de_baja": false,
  "documentos": []
}

200 con el conductor · 404 no_encontrado · 422 datos_invalidos si la referencia viene vacía o pasa de 80 caracteres.

PUT /api/v1/conductores/{referencia}

Crea el conductor si no existe, o lo actualiza (fusión, ver la nota arriba). Todo o nada, igual que el de vehículo.

Cuerpo

{
  "nombre": "Ana Ríos",
  "celular": "+573001234567",
  "correo": "[email protected]",
  "documentos": [{"tipo": "LICENCIA_CONDUCCION", "fecha": "2030-05-01"}]
}

curl

curl -X PUT https://placasegura.co/api/v1/conductores/C-045 \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"nombre": "Ana Ríos", "celular": "+573001234567"}'

Respuesta de ejemplo

{
  "referencia": "C-045",
  "nombre": "Ana Ríos",
  "celular": "+573001234567",
  "correo": null,
  "dado_de_baja": false,
  "documentos": []
}

201 si lo creó, 200 si lo actualizó, con el conductor · 422 datos_invalidos · 409 tope_flota (500 conductores, o el tope de documentos del conductor) · 409 conflicto · 400 sin cuerpo.

DELETE /api/v1/conductores/{referencia}

Borra el conductor, sus documentos y lo desasigna de sus vehículos. Su contacto también se borra, salvo que esté dado de baja.

curl

curl -X DELETE https://placasegura.co/api/v1/conductores/C-045 \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

204 sin cuerpo · 404 no_encontrado.

Documentos del conductor

Igual que los del vehículo, pero por {referencia} y con un tipo que aplique a conductor.

PUT /api/v1/conductores/{referencia}/documentos/{tipo}

Crea o actualiza un documento suelto del conductor.

Cuerpo

{"fecha": "2030-05-01"}

curl

curl -X PUT https://placasegura.co/api/v1/conductores/C-045/documentos/LICENCIA_CONDUCCION \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"fecha": "2030-05-01"}'

Respuesta de ejemplo

{"tipo": "LICENCIA_CONDUCCION", "nombre": "Licencia de conducción", "fecha": "2030-05-01", "dias": 1313, "fuente": "api"}

200 con el documento · 404 no_encontrado si el conductor no existe · 422 datos_invalidos · 409 tope_flota si el documento es nuevo y el conductor ya llegó a su tope de documentos.

DELETE /api/v1/conductores/{referencia}/documentos/{tipo}

Quita un documento del conductor. `OTRO` necesita el `nombre` (en el cuerpo o en `?nombre=`).

curl

curl -X DELETE https://placasegura.co/api/v1/conductores/C-045/documentos/LICENCIA_CONDUCCION \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

204 sin cuerpo · 404 no_encontrado · 422 datos_invalidos.

Licencia del conductor (RUNT)

primer_apellido es opcional: sin él, PlacAPI cobra el doble de créditos, pero en tu tope mensual cuenta como una sola consulta igual. Se guarda la fecha que vence primero entre las categorías activas de la licencia; si todas ya vencieron, la más reciente.

POST /api/v1/conductores/{referencia}/licencia

Trae del RUNT la licencia de conducción del conductor y la guarda (con `fuente: "runt"`).

Cuerpo

{"tipo_documento": "CC", "numero_documento": "1020304050", "primer_apellido": "PÉREZ"}

curl

curl -X POST https://placasegura.co/api/v1/conductores/C-045/licencia \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"tipo_documento": "CC", "numero_documento": "1020304050", "primer_apellido": "PÉREZ"}'

Respuesta de ejemplo

{
  "documentos": [{"tipo": "LICENCIA_CONDUCCION", "fecha": "2030-05-01"}],
  "consultas_restantes": 28
}

200 con la licencia guardada y las consultas que te quedan · 422 datos_invalidos · 404 no_encontrado (el conductor no es de tu empresa, o no hay licencias activas para ese documento) · 429 tope_runt · 429 limite (también sin primer_apellido, después de 10 consultas en una hora que el RUNT respondió pidiendo el apellido) · 503 runt_no_disponible.

Vencimientos

dias puede ser negativo: significa que el documento ya venció. La lista sale ordenada por dias (lo más urgente primero).

GET /api/v1/vencimientos?dias=N

Lo que vence en los próximos `N` días (1 a 365, 30 por defecto) y lo ya vencido, de toda tu flota.

curl

curl "https://placasegura.co/api/v1/vencimientos?dias=15" \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…"

Respuesta de ejemplo

[
  {"placa": "ABC123", "tipo": "SOAT", "nombre": "SOAT", "fecha": "2026-09-20", "dias": -5},
  {"conductor_referencia": "C-045", "conductor_nombre": "Ana Ríos", "tipo": "LICENCIA_CONDUCCION", "nombre": "Licencia de conducción", "fecha": "2026-10-08", "dias": 13}
]

200 con la lista · 422 datos_invalidos si dias no es un entero entre 1 y 365.

Lote

Cada operación del lote corre su propia transacción: una que falla no detiene a las demás. Los conductores se procesan primero, así un vehículo del mismo lote puede asignarse a un conductor recién creado. indice es la posición dentro de su propia lista (vehiculos o conductores), no la del lote completo.

POST /api/v1/lote

Crea o actualiza hasta 500 vehículos y conductores en una sola petición (la misma regla del `PUT` de cada uno, operación por operación).

Cuerpo

{
  "conductores": [{"referencia": "C-045", "nombre": "Ana Ríos"}],
  "vehiculos": [{"placa": "ABC123", "conductor_referencia": "C-045", "documentos": [{"tipo": "SOAT", "fecha": "2026-11-15"}]}]
}

curl

curl -X POST https://placasegura.co/api/v1/lote \
  -H "Authorization: Bearer ps_live_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  --data '{"conductores": [{"referencia": "C-045", "nombre": "Ana Ríos"}], "vehiculos": [{"placa": "ABC123", "conductor_referencia": "C-045"}]}'

Respuesta de ejemplo

{
  "resultados": [
    {"indice": 0, "tipo": "conductor", "clave": "C-045", "estado": "ok"},
    {"indice": 0, "tipo": "vehiculo", "clave": "ABC123", "estado": "ok"},
    {"indice": 1, "tipo": "vehiculo", "clave": "MAL0PLACA", "estado": "error", "error": {"codigo": "datos_invalidos", "mensaje": "Esa placa no es válida."}}
  ]
}

200 siempre (mira estado en cada resultado) · 422 datos_invalidos si el lote viene vacío, trae más de 500 operaciones o tiene otra forma · 429 limite, con más de 6 lotes por minuto de tu empresa (aparte de las 120 peticiones por minuto de tu llave y de tu empresa).

RUNT

Dos rutas de la API consultan el RUNT de verdad, vía PlacAPI, y gastan crédito real: la del SOAT y la tecnomecánica de una placa (con el documento del propietario), y la de la licencia de un conductor.

Qué trae. Del vehículo, el SOAT y la revisión técnico-mecánica vigentes, cotejados con el documento del propietario en el RUNT: puede ser cédula (CC), NIT sin dígito de verificación (NIT, 900.123.456-7 se manda como 900123456), cédula de extranjería (CE), permiso por protección temporal (PPT), pasaporte (PA) o tarjeta de identidad (TI). Del conductor, la licencia de conducción: se guarda la fecha que vence primero entre sus categorías activas.
Tope mensual. Cada empresa tiene un tope de consultas al RUNT (30 por defecto, lo ajusta PlacaSegura por empresa), que se reinicia el día 1 de cada mes en el calendario de Bogotá. Cuenta toda consulta que llegó a PlacAPI, salga bien o no; no cuenta una consulta que el sitio frenó antes de llamar a PlacAPI (limite) ni una que PlacAPI respondió sin cobrar crédito (una licencia sin primer_apellido en la que el RUNT pide el apellido; después de 10 de esas en una hora, las que llegan sin apellido responden limite). Una licencia sin primer_apellido cuesta el doble en PlacAPI, pero cuenta como una sola consulta en tu tope igual.
El documento no se guarda. El número de documento (y el apellido) solo vive en memoria durante la llamada: no queda en ninguna tabla, no sale en la respuesta ni en los errores, y no va a los registros internos.
Los vencidos se guardan. Si el RUNT devuelve una fecha ya pasada, se guarda igual (para que sepas que ese documento está vencido) y aparece en documentos con dias negativo, pero no genera un aviso nuevo por sí sola. La excepción es la revisión técnico-mecánica que el RUNT marca como no exigible (vehículos nuevos): esa no se guarda.

Catálogo de documentos

Los tipos que puede llevar un vehículo o un conductor, con sus umbrales de aviso (días de anticipación) y la norma que los exige, cuando aplica. La misma tabla sale de GET /catalogo.

Tipo	Nombre	Aplica a	Avisa (días antes)	Norma
SOAT	SOAT	vehiculo	30, 7, 1	Ley 769 de 2002
RTM	Revisión técnico-mecánica	vehiculo	30, 7, 1	Ley 769 de 2002
TODO_RIESGO	Seguro todo riesgo	vehiculo	30, 7, 1	—
REVISION_PREVENTIVA	Revisión preventiva	vehiculo	7, 1	Res. 315 de 2013
TARJETA_OPERACION	Tarjeta de operación	vehiculo	30, 7, 1	Decreto 1079 de 2015
RC_CONTRACTUAL	Póliza de responsabilidad civil contractual	vehiculo	30, 7, 1	Decreto 1079 de 2015
RC_EXTRACONTRACTUAL	Póliza de responsabilidad civil extracontractual	vehiculo	30, 7, 1	Decreto 1079 de 2015
POLIZA_MERCANCIA	Póliza de la mercancía transportada	vehiculo	30, 7, 1	Decreto 1609 de 2002
IMPUESTO_VEHICULAR	Impuesto vehicular	vehiculo	30, 7, 1	departamental
EXTINTOR	Recarga del extintor	vehiculo	30, 7, 1	Art. 30, Ley 769 de 2002
BOTIQUIN	Botiquín	vehiculo	7, 1	Art. 30, Ley 769 de 2002
LICENCIA_CONDUCCION	Licencia de conducción	conductor	30, 7, 1	Ley 1383 de 2010, art. 22
CURSO_MERCANCIAS_PELIGROSAS	Curso de mercancías peligrosas	conductor	30, 7, 1	Res. 1223 de 2014
OTRO	Otro	cualquiera	30, 7, 1	—

Errores

Todo error tiene la forma {"error": {"codigo", "mensaje"}}.

Código	HTTP	Cuándo
no_autorizado	401	Falta la llave, no tiene la forma ps_live_…, no existe o fue revocada. La respuesta trae la cabecera WWW-Authenticate: Bearer.
empresa_no_aprobada	403	La empresa de la llave todavía no está aprobada, o fue suspendida. Se comprueba en cada petición: suspender la empresa corta el acceso al instante.
no_encontrado	404	La placa, la referencia, el tipo de documento o la ruta no existen. Una placa o referencia de otra empresa da el mismo 404 que una que no existe: nunca se distingue, para no filtrar qué tienen otras empresas.
datos_invalidos	400 / 411 / 413 / 422	400 con el cuerpo vacío en un PUT o POST, o con un JSON mal formado. 411 si falta Content-Length. 413 si el cuerpo pasa de 256 KB. 422 con la placa, la fecha, el tipo de documento, la referencia u otro campo con forma inválida.
conflicto	409	Otra petición escribió el mismo dato al mismo tiempo (choque de clave única). Reintenta la petición.
tope_flota	409	Tu empresa ya tiene 500 vehículos, o ya tiene 500 conductores; o el vehículo o conductor ya tiene 10 documentos OTRO, o 25 documentos en total, y el que mandas es nuevo (actualizar la fecha de uno que ya existe siempre pasa).
limite	429	Pasaste las 120 peticiones por minuto de tu llave, las 120 por minuto de tu empresa (sumando todas sus llaves), los 6 POST /lote por minuto de tu empresa, o las 60 llaves rechazadas por minuto desde tu IP (todas con la cabecera Retry-After: 60); o el sitio está frenando temporalmente las consultas al RUNT de todas las empresas, o tu empresa ya hizo en la última hora 10 consultas de licencia sin primer_apellido que el RUNT respondió pidiendo el apellido (estas dos sin Retry-After).
tope_runt	429	Tu empresa llegó a su tope mensual de consultas al RUNT (30 por defecto).
documento_no_coincide	422	En una consulta al RUNT, el documento que enviaste no es el del propietario activo de esa placa.
runt_no_disponible	503	El RUNT (vía PlacAPI) no respondió o no tenía créditos, o respondió pero no se pudieron guardar las fechas.
error_interno	500	Un error de nuestro lado; el mensaje nunca lleva detalles internos. Vuelve a intentarlo.

Límites

120 peticiones por minuto, por llave. 429 limite con Retry-After: 60.
120 peticiones por minuto, por empresa. sumando todas las llaves de tu empresa, aparte del de cada llave: más llaves no dan más cupo. 429 limite con Retry-After: 60.
60 llaves rechazadas por minuto, por IP. después de 60 respuestas 401 no_autorizado desde la misma IP en un minuto, 429 limite con Retry-After: 60.
10 consultas de licencia por hora que piden el apellido, por empresa. si el RUNT responde que necesita el primer_apellido, esa consulta no cuenta para tu tope mensual; después de 10 en una hora, las que llegan sin primer_apellido responden 429 limite.
6 POST /lote por minuto, por empresa. aparte de las 120 por llave y por empresa; 429 limite con Retry-After: 60.
256 KB por cuerpo. en PUT, POST y DELETE con cuerpo; 411 sin Content-Length, 413 si lo pasa.
500 operaciones por POST /lote. entre vehículos y conductores juntos.
500 vehículos y 500 conductores por empresa. 409 tope_flota al llegar.
10 documentos OTRO y 25 documentos en total, por vehículo y por conductor. 409 tope_flota al crear uno nuevo pasado el tope; actualizar la fecha de uno que ya existe siempre pasa. Cuenta lo cargado por el panel, el CSV y la API.
50 documentos por petición. en el arreglo documentos de un PUT de vehículo o conductor.

¿Ya tienes cuenta? Crea o revisa tus llaves en la pestaña API de tu panel.