Ir al contenido

Errores

Cuando algo no sale bien, Colonix te lo dice con un código de estado HTTP y un mensaje que siempre tiene la misma forma. Tu programa solo necesita leer un campo, type, para saber qué pasó y qué hacer: corregir la petición, esperar o reintentar.

Todos los errores llegan con Content-Type: application/problem+json, el formato estándar de RFC 9457:

404 Not Found
{
"type": "/errors/postal-code-not-found",
"title": "Postal code not found",
"status": 404,
"detail": "Postal code 00000 does not exist in the current catalog."
}
Campo Qué es ¿Lo puedes usar en tu código?
type Identificador del error Sí. Es estable: no cambia dentro de /v1
title Nombre corto del error, en inglés No: es para personas y puede cambiar
status El mismo código de estado HTTP de la respuesta Sí
detail Explicación de este caso concreto, en inglés No: muéstralo en tus registros, pero no lo compares

Decide siempre con type, no con detail ni solo con el estado: hay estados que comparten varios tipos (por ejemplo, 404 es tanto una ruta mal escrita como un código postal que no existe).

Cada type también es una dirección: relativa a la API, como indica el estándar. Si abres https://colonix.silgaru.mx/errors/postal-code-not-found en el navegador, llegas a la explicación de ese error en esta página.

Estado ¿Reintentar? Qué hacer
400 No Corrige la petición: el mismo envío siempre dará el mismo error
401, 403 No Revisa la llave o el plan
404 No El recurso no existe; no es una falla del servicio
405 No Usa GET o HEAD
421 No Usa la dirección https://colonix.silgaru.mx
429 con rate-limited Sí Espera y reintenta, cada vez esperando más
429 con quota-exceeded No Espera al siguiente mes o cambia de plan
500, 503 Sí Reintenta unas cuantas veces con espera creciente

En Planes, cuotas y el error 429 hay un ejemplo de reintentos en JavaScript. Ningún error cuenta para tu cuota.

Como cualquier servicio en internet, Colonix puede tardar o fallar por un momento. Que eso no detenga a quien llena tu formulario:

  • Pon un tiempo límite. Una consulta normal responde en milisegundos, pero de vez en cuando la primera de una ráfaga tarda unos segundos. Con 5 segundos de límite (10 para el lote) no cortas una respuesta lenta y tampoco dejas esperando a nadie.
  • Reintenta solo lo que se puede reintentar (500, 503 y 429 con rate-limited), dos o tres veces con espera creciente. Nunca reintentes en un ciclo sin fin.
  • Deja capturar a mano. Si no hay respuesta, muestra el campo de colonia como texto libre y valida la combinación después, cuando la API vuelva, con /v1/validate/postal-code-settlement.
  • Aprovecha lo que ya consultaste. Las respuestas correctas traen stale-if-error=604800: si tu aplicación o tu CDN guarda respuestas, puede seguir usando la copia anterior hasta 7 días cuando la API no responde (Caché y revalidación).
Consulta con tiempo límite y respaldo
async function coloniasDe(cp) {
try {
const r = await fetch(`https://colonix.silgaru.mx/v1/postal-codes/${cp}`, {
headers: { "x-api-key": process.env.COLONIX_API_KEY },
signal: AbortSignal.timeout(5000),
});
if (r.ok) return (await r.json()).settlements.map((s) => s.name);
if (r.status === 404) return []; // el CP no existe: no es una falla
} catch {
// tiempo agotado o sin red
}
return null; // sin respuesta: muestra la colonia como texto libre y valida después
}

Un parámetro falta, viene más de una vez o tiene un valor que no se acepta. detail dice cuál:

GET /v1/postal-codes/0670
{
"type": "/errors/invalid-parameter",
"title": "Invalid parameter",
"status": 400,
"detail": "The postal code must have 5 digits."
}

Otros casos reales: limit must be an integer between 1 and 500. o Unknown block in include: foo. Allowed: sat, location, metro. (en la validación, Allowed: sat, cfdi.) Corrige el parámetro; los valores aceptados de cada uno están en la referencia.

La petición trae un parámetro que el endpoint no tiene. Colonix no lo ignora: si lo hiciera, un nombre mal escrito (?colonia=roma en lugar de ?q=roma) te devolvería resultados sin filtrar y no te darías cuenta. detail dice cuál sobra. Si el parámetro no existe en ninguna ruta:

GET /v1/settlements?colonia=roma
{
"type": "/errors/unknown-parameter",
"title": "Unknown parameter",
"status": 400,
"detail": "colonia is not a parameter of the API. Each endpoint lists its parameters in the documentation."
}

Si existe, pero en otro endpoint, detail también dice cuáles acepta este:

GET /v1/sat/discrepancies?postal_code=01000
{
"type": "/errors/unknown-parameter",
"title": "Unknown parameter",
"status": 400,
"detail": "postal_code is not a parameter of this endpoint. Accepted: cursor, entity, limit, missing_in, state."
}

Los nombres distinguen mayúsculas (Q no es q). Revisa también lo que agregan tus herramientas sin que lo veas: jQuery con cache: false pone _=<número> y las campañas, utm_source; quítalos de las peticiones a la API. Los parámetros de cada endpoint están en la referencia.

Estabas paginando y el catálogo se actualizó entre una página y otra. Los cursores solo valen para la versión del dato que los emitió, para que nunca mezcles páginas de dos versiones. Vuelve a empezar desde la primera página, sin cursor.

El valor de since en /v1/changes no es una versión del dato publicada. Usa el data_version que guardaste de una respuesta anterior, tal cual.

Pediste un código postal en una fecha (as_of) fuera del historial: antes de que empezara o después de hoy (en la Ciudad de México). Colonix solo responde lo que registró: SEPOMEX desde history_since y el SAT desde sat_history_since (los dos en /v1/meta). El detail dice desde cuándo. Ver Cómo estaba un código postal en una fecha.

La petición no trae el encabezado x-api-key (o la llave viene en otro lugar). Agrégalo. Detalle en Llaves.

La llave no existe o fue revocada. Revisa que esté completa y sin espacios; si la cambiaste, usa la nueva. Una llave recién creada tarda unos segundos en empezar a funcionar: si la acabas de crear, espera un momento y repite la petición.

La llave está suspendida. Escríbenos desde tu cuenta.

Tu plan no incluye esa consulta (por ejemplo, el CP de un punto en el plan Gratis). No lo reintentes: revisa qué incluye cada plan.

El código postal tiene el formato correcto (5 dígitos), pero no está en el catálogo vigente (o, con as_of, no estaba en esa fecha). No es una falla del servicio: es la respuesta a “¿existe este código postal?”, y no cuenta para tu cuota. Ver Un código postal que no existe.

La clave de estado no existe (son de 01 a 32). La lista está en /v1/states.

La clave de municipio no existe en ese estado. La lista está en /v1/states/{state}/municipalities.

Ningún área de código postal contiene el punto que mandaste a /v1/reverse: suele ser un punto en el mar, fuera de México o con la latitud y la longitud invertidas. Revisa las coordenadas; para buscar el código postal más cercano, usa /v1/nearby.

La ruta no existe. Revisa que empiece con /v1/, que esté en minúsculas y que coincida con la referencia.

La API solo acepta GET y HEAD. La respuesta trae el encabezado Allow: GET, HEAD.

La petición no llegó a https://colonix.silgaru.mx, la única dirección de la API. Suele pasar con una dirección vieja o copiada de otro lado. Cambia la URL base de tu integración; la llave sigue siendo la misma. Esta respuesta no revisa la llave ni cuenta para tu cuota.

Llegaste a las consultas de tu plan en este mes. No reintentes: la API responde lo mismo hasta el día 1 a las 00:00 UTC o hasta que cambies de plan. Nunca se cobra un excedente. El encabezado Retry-After dice cuántos segundos faltan para ese momento.

Mandaste demasiadas peticiones en poco tiempo: el límite es de 300 por minuto por llave y por IP. Espera unos segundos y reintenta, duplicando la espera en cada intento; Retry-After dice cuántos segundos esperar. Esta respuesta trae el mismo cuerpo que los demás errores, pero con Content-Type: application/json.

Algo falló de nuestro lado. Reintenta unas cuantas veces con espera creciente; si sigue, escríbenos.

503 Service Unavailable significa que el servicio no está disponible por un momento (mantenimiento o protección). Puede llegar sin cuerpo JSON: decide por el estado y reintenta más tarde.

Depende de lo que preguntes. Si pides un recurso por su clave, la respuesta a “no existe” es 404. Si buscas, validas o pides varios, la respuesta es 200 y el resultado lo dice:

Petición Si el código postal no existe
GET /v1/postal-codes/{code} 404 con postal-code-not-found
GET /v1/sat/postal-codes/{code} 404 con postal-code-not-found si no está ni en el SAT ni en SEPOMEX (si está en uno solo, responde 200 y lo indica con in_sat e in_sepomex)
GET /v1/validate/postal-code-settlement 200 con "outcome": "postal_code_not_found", "postal_code_exists": false y "valid": false
GET /v1/autocomplete, GET /v1/postal-codes 200 con "data": []
GET /v1/postal-codes/batch 200; ese código va con "found": false y su error

Ninguna de estas respuestas cuenta como falla, y los 404 no cuentan para tu cuota.

En /v1/postal-codes/batch, un código malo nunca hace fallar a los demás: la respuesta es 200 y cada elemento trae su propio resultado o su propio error, con la misma forma de arriba.

GET /v1/postal-codes/batch?codes=06700,00000,abc
{
"data": [
{ "postal_code": "06700", "found": true, "result": { "postal_code": "06700", "…": "…" }, "error": null },
{
"postal_code": "00000",
"found": false,
"result": null,
"error": {
"type": "/errors/postal-code-not-found",
"title": "Postal code not found",
"status": 404,
"detail": "Postal code 00000 does not exist in the current catalog."
}
},
{
"postal_code": "abc",
"found": false,
"result": null,
"error": {
"type": "/errors/invalid-parameter",
"title": "Invalid parameter",
"status": 400,
"detail": "The postal code must have 5 digits."
}
}
],
"data_version": "2026.11.05-36a7823b"
}

Los errores de la petición (400 y 404) traen Cache-Control: public, max-age=300: puedes guardarlos 5 minutos. Algunos (una ruta mal formada o un parámetro que no existe en ninguna ruta) llegan con no-store; da igual: se repiten mientras no corrijas la petición. Los de llave, plan, cuota y servicio (401, 403, 429 y 5xx) traen Cache-Control: no-store: no los guardes, porque dependen de tu cuenta o del momento.