Entornos y límites
Hosts
| Entorno | Host | Para qué |
|---|---|---|
| Producción | https://api.tributax.app | consultas reales, que consumen cupo y saldo |
| Desarrollo | https://dev.api.tributax.app | integración y pruebas |
:::warning No hardcodees el host
Selecciona el host por variable de entorno o por canal de build. Una URL fija en el código es la
forma más común de consultar producción durante una prueba —y la colección de Postman de la que
sale este portal traía justamente eso: una copia apuntando a https://api.tributax.app en duro.
:::
Los dos entornos tienen bases de datos distintas. Las credenciales de tu integración y las consultas que tiene habilitadas existen en uno o en otro, nunca en ambos por arte de magia: pide credenciales para cada entorno que vayas a usar.
En producción, cada consulta que se resuelve bien consume del saldo o del cupo de tu integración. Prueba en desarrollo.
Límites de peticiones — son varias capas, no una
La API aplica límites independientes por capa. Un integrador que solo conozca el global se
sorprenderá con un 429 mucho antes de acercarse a él.
| Capa | Ámbito | Se cuenta por | Límite | Respuesta al excederlo |
|---|---|---|---|---|
| Global | toda la API | dirección IP | 100 / 15 min | 429 con el cuerpo por defecto de express-rate-limit |
| RENAP | POST /renap/buscar-cui | nombre de la integración | 30 / min | 429 {"error":"Rate limit exceeded."} |
| RTU | POST /rtu/nits | nombre de la integración | 50 / min | 429 {"error":"Rate limit exceeded."} |
| Catálogos | POST /catalogos/cui-nit, /rtu, /omisos — compartido entre los tres | la integración | 30 / min | 429 {"message":"Demasiadas consultas seguidas. Intenta en un minuto."} |
Todos estos límites se suman al global: consumen cupo global además del suyo.
Fíjate en la clave del cuerpo. RENAP y RTU (/rtu/nits) responden con error, mientras que
los catálogos (/catalogos/*) y el resto de la API responden con message. Es una de las
razones por las que el catálogo de errores insiste en que el
discriminante fiable es el status HTTP, no la forma del cuerpo.
:::caution El límite nominal no es una garantía de capacidad Todos estos contadores viven en memoria del proceso que atiende la petición, así que el límite efectivo depende de cuántos procesos haya sirviendo y de cuál te toque — algo que ni tú ni nosotros controlamos por petición.
Dimensiona tu integración por el número nominal y trata cualquier margen extra como suerte, no como contrato: el límite puede endurecerse sin previo aviso. Y como el contador global es por IP, si sales por una IP compartida con otro sistema, ese otro sistema gasta de tu cupo. :::
Cómo reaccionar a un 429
Reintenta con retroceso exponencial y algo de aleatoriedad. Ninguna de estas capas devuelve
Retry-After, así que:
- Las ventanas por minuto (RENAP, RTU y Catálogos) se reinician a más tardar 60 s después de la primera petición de la ventana.
- La ventana global es de 15 min, así que agotarla es caro: conviene ir despacio antes que reintentar fuerte.
Para cargas grandes usa la forma por lote en vez de repetir la llamada unitaria:
POST /rtu/nits consulta hasta 50 NIT de una vez.
📄 Estado de verificación: leído del código del backend. Los límites no se han ejercido contra el entorno desplegado en esta entrega.