Planes, cuotas y el error 429
Cada plan habilita un conjunto de consultas y trae una cantidad de consultas al mes. Todos usan los mismos datos y la misma velocidad. Cuando llegas a tu cuota, la API deja de responder hasta el mes siguiente o hasta que cambies de plan: nunca se cobra un excedente.
Los planes
Section titled “Los planes”| Plan | Precio al mes | Consultas al mes | Agrega |
|---|---|---|---|
| Gratis | $0 | 10,000 | Consulta por código postal, búsqueda, autocompletado, validación, historial y catálogos |
| Básico | $199 MXN, IVA incluido | 100,000 | Las claves del SAT, la ubicación y la zona metropolitana de cada código postal, el código postal de un punto y los códigos postales cercanos |
| Negocio | $599 MXN, IVA incluido | 1,000,000 | La consulta en lote, los cambios del catálogo y las diferencias entre SEPOMEX y el SAT |
| Enterprise | desde $1,999 MXN, IVA incluido | 5,000,000 o a la medida | Volumen y condiciones a la medida, soporte directo en español |
Cada plan incluye todo lo del anterior. Los planes de pago se solicitan desde tu cuenta y empiezan con 14 días de prueba.
Qué incluye cada plan
Section titled “Qué incluye cada plan”| Endpoint o parámetro | Gratis | Básico | Negocio | Enterprise |
|---|---|---|---|---|
GET /v1/postal-codes/{code} |
✓ | ✓ | ✓ | ✓ |
GET /v1/postal-codes/{code}/history |
✓ | ✓ | ✓ | ✓ |
as_of en GET /v1/postal-codes/{code} (cómo estaba en una fecha) |
✓ | ✓ | ✓ | ✓ |
GET /v1/postal-codes y GET /v1/settlements (búsqueda) |
✓ | ✓ | ✓ | ✓ |
GET /v1/autocomplete |
✓ | ✓ | ✓ | ✓ |
GET /v1/validate/postal-code-settlement |
✓ | ✓ | ✓ | ✓ |
Catálogos: /v1/states, /v1/states/{state}/municipalities, /v1/municipalities/{state}/{municipality}/settlements, /v1/settlement-types |
✓ | ✓ | ✓ | ✓ |
GET /v1/meta |
✓ | ✓ | ✓ | ✓ |
include=location e include=metro |
demo | ✓ | ✓ | ✓ |
GET /v1/reverse y GET /v1/nearby |
✓ | ✓ | ✓ | |
include=sat |
demo | ✓ | ✓ | ✓ |
include=cfdi en la validación (el domicilio para Carta Porte y Comercio Exterior) |
✓ | ✓ | ✓ | |
GET /v1/sat/postal-codes/{code}, también con as_of |
demo | ✓ | ✓ | ✓ |
GET /v1/sat/discrepancies |
✓ | ✓ | ||
GET /v1/postal-codes/batch |
✓ | ✓ | ||
GET /v1/changes |
✓ | ✓ |
demo: solo en los cinco códigos postales de demostración (06700, 44100, 64000, 22000 y
77500), en /v1/postal-codes/{code}, su historial y /v1/sat/postal-codes/{code}. Así puedes ver la
ubicación, la zona metropolitana y el SAT antes de contratar el plan que los incluye. En la
validación, include=sat e include=cfdi necesitan un plan de pago aunque el código sea de
demostración.
Cómo se cuentan las consultas
Section titled “Cómo se cuentan las consultas”- Cada respuesta correcta cuenta una consulta: estado
2xx, o304 Not Modifiedcuando revalidas conIf-None-Match. - Las respuestas con error no cuentan, sea cual sea su estado:
400,401,403,404,429o5xx. Por ejemplo, pedir un código postal que no existe responde404y no gasta nada. - La consulta en lote cuenta una por cada código postal que pidas en
codes(hasta 100), lo encuentre o no. - Los parámetros
includeno cuestan extra:include=location,metro,satsigue siendo una consulta. - La llave de prueba no cuenta (Llaves).
El periodo es el mes calendario en tiempo universal (UTC): la cuota se reinicia el día 1 a las 00:00 UTC, que en el centro de México es las 18:00 del último día del mes anterior. Tu consumo del mes está en tu cuenta, y te avisamos por correo cuando llegas al 80 % y al 100 % de tu cuota (puedes dejar de recibir esos avisos desde tu cuenta).
Cuando tu plan no incluye una consulta: 403
Section titled “Cuando tu plan no incluye una consulta: 403”Si pides algo que tu plan no incluye, la respuesta es 403 y no cuenta para tu cuota:
{ "type": "/errors/plan-not-allowed", "title": "Plan not allowed", "status": 403, "detail": "Your plan does not include this endpoint or option."}No lo reintentes: la respuesta no cambia hasta que cambies de plan. Si tu aplicación ofrece una función que depende de un plan (por ejemplo, las claves del SAT), revisa este error y ocúltala o avísale al usuario.
Cuando llegas al límite: 429
Section titled “Cuando llegas al límite: 429”Hay dos razones para un 429, y se distinguen por type:
type |
Qué pasó | Qué hacer |
|---|---|---|
/errors/quota-exceeded |
Llegaste a las consultas de tu plan en este mes | No reintentes: espera al día 1 (UTC) o cambia de plan. Retry-After dice cuántos segundos faltan |
/errors/rate-limited |
Mandaste demasiadas peticiones en poco tiempo | Reintenta en unos segundos, cada vez esperando más |
{ "type": "/errors/quota-exceeded", "title": "Monthly quota exceeded", "status": 429, "detail": "Your plan reached its monthly quota. Upgrade your plan or wait for the next period."}Para rate-limited, espera antes de reintentar y duplica la espera en cada intento (por ejemplo,
1, 2, 4 y 8 segundos, con un poco de azar para que tus servidores no reintenten todos a la vez), y
deja de intentar después de unos cuantos. Así se ve en JavaScript:
// Reintenta solo los 429 por ráfaga y los 5xx; nunca la cuota agotada ni los 4xxasync function consultar(url, intentos = 4) { for (let i = 0; ; i++) { const res = await fetch(url, { headers: { "x-api-key": process.env.COLONIX_API_KEY }, signal: AbortSignal.timeout(5000), }); if (res.ok || res.status === 304) return res;
const error = await res.json().catch(() => ({})); const reintentable = error.type === "/errors/rate-limited" || res.status >= 500; if (!reintentable || i + 1 >= intentos) { throw new Error(`${res.status} ${error.type ?? ""}: ${error.detail ?? ""}`); } const espera = 2 ** i * 1000 + Math.random() * 250; await new Promise((r) => setTimeout(r, espera)); }}© 2026 Silgaru