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.
La forma de un error
Section titled “La forma de un error”Todos los errores llegan con Content-Type: application/problem+json, el formato estándar de
RFC 9457:
{ "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.
Qué hacer según el error
Section titled “Qué hacer según el error”| 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.
Si la API no responde
Section titled “Si la API no responde”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,503y429conrate-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).
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}Todos los errores
Section titled “Todos los errores”400 · Petición inválida
Section titled “400 · Petición inválida”invalid-parameter
Section titled “invalid-parameter”Un parámetro falta, viene más de una vez o tiene un valor que no se acepta. detail dice cuál:
{ "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.
unknown-parameter
Section titled “unknown-parameter”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:
{ "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:
{ "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.
cursor-expired
Section titled “cursor-expired”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.
unknown-version
Section titled “unknown-version”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.
as-of-out-of-range
Section titled “as-of-out-of-range”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.
401 · Sin autenticación
Section titled “401 · Sin autenticación”missing-api-key
Section titled “missing-api-key”La petición no trae el encabezado x-api-key (o la llave viene en otro lugar). Agrégalo. Detalle
en Llaves.
invalid-api-key
Section titled “invalid-api-key”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.
403 · Sin permiso
Section titled “403 · Sin permiso”api-key-suspended
Section titled “api-key-suspended”La llave está suspendida. Escríbenos desde tu cuenta.
plan-not-allowed
Section titled “plan-not-allowed”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.
404 · No existe
Section titled “404 · No existe”postal-code-not-found
Section titled “postal-code-not-found”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.
state-not-found
Section titled “state-not-found”La clave de estado no existe (son de 01 a 32). La lista está en /v1/states.
municipality-not-found
Section titled “municipality-not-found”La clave de municipio no existe en ese estado. La lista está en
/v1/states/{state}/municipalities.
location-not-covered
Section titled “location-not-covered”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.
route-not-found
Section titled “route-not-found”La ruta no existe. Revisa que empiece con /v1/, que esté en minúsculas y que coincida con la
referencia.
405 · Método no permitido
Section titled “405 · Método no permitido”method-not-allowed
Section titled “method-not-allowed”La API solo acepta GET y HEAD. La respuesta trae el encabezado Allow: GET, HEAD.
421 · Dirección equivocada
Section titled “421 · Dirección equivocada”misdirected-request
Section titled “misdirected-request”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.
429 · Demasiadas consultas
Section titled “429 · Demasiadas consultas”quota-exceeded
Section titled “quota-exceeded”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.
rate-limited
Section titled “rate-limited”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.
500 y 503 · Falla del servicio
Section titled “500 y 503 · Falla del servicio”internal-error
Section titled “internal-error”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.
Un código postal que no existe
Section titled “Un código postal que no existe”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.
Errores dentro de la consulta en lote
Section titled “Errores dentro de la consulta en lote”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.
{ "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"}Caché de los errores
Section titled “Caché de los errores”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.
© 2026 Silgaru