Ir al contenido

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.

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.

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.

  • Cada respuesta correcta cuenta una consulta: estado 2xx, o 304 Not Modified cuando revalidas con If-None-Match.
  • Las respuestas con error no cuentan, sea cual sea su estado: 400, 401, 403, 404, 429 o 5xx. Por ejemplo, pedir un código postal que no existe responde 404 y 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 include no cuestan extra: include=location,metro,sat sigue 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:

403 Forbidden
{
"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.

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
429 Too Many Requests
{
"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 4xx
async 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));
}
}