Resolución de problemas

Lo que ves cuando algo falla, qué lo causa casi siempre y qué hacer. Busca por el código que trae la respuesta en error.code: es lo que no cambia.

6 min de lecturaRevisado el 25 de octubre de 2026

Antes de nada: lee success, error.code y meta.requestId de la respuesta. El catálogo de errores explica cada código a fondo; esta página te lleva más rápido al arreglo de los síntomas más comunes.

No me deja entrar

Autenticación y permisos
Qué ves	Causa más común	Qué hacer
`401 AUTH_REQUIRED`	Falta la cabecera `Authorization`, o no empieza por `Bearer` , o el token va en la URL o en el cuerpo (ahí se ignora).	Envía `Authorization: Bearer hk_TU_API_KEY` en cada petición. Mira Autenticación.
`401 AUTH_INVALID_KEY`	Error de escritura al copiar, mayúsculas en una clave que va en minúscula, una clave eliminada o vencida, o la clave de otro entorno.	Copia de nuevo el valor que Cloud mostró al crearla. Si no lo tienes, crea otra clave: la original no se puede recuperar. Mira Tu clave de API.
`403 ACCOUNT_NOT_ACTIVE`	La organización de la clave no está activa.	Escribe a soporte con el `requestId`.
`403 AUTH_IP_NOT_ALLOWED`	La clave se creó con una lista de redes y llamaste desde otra. Detrás de un NAT, un proxy o una nube, la IP de salida suele no ser la que esperas.	Compara `meta.clientIp` de la respuesta con las redes de la clave. La lista no se puede cambiar: llama desde una red permitida o crea otra clave.
`403 AUTH_SERVICE_NOT_ALLOWED`	La clave no tiene el servicio del endpoint, o tu organización lo apagó.	Crea una clave con ese servicio: el alcance no se puede cambiar después. Mira Requisitos.
`403 AUTH_CAPABILITY_NOT_ALLOWED`	Al endpoint le falta una capacidad de la cuenta: `account` o `directory`.	Pídele al propietario de tu organización una clave con esa capacidad: solo él crea claves. Mira Tu clave de API.

Me dicen que espere

Límites de uso
Qué ves	Causa más común	Qué hacer
`429 RATE_TPS_EXCEEDED`	Superaste el límite de ese endpoint para tu organización. El ping admite 20 por minuto; cada endpoint dice el suyo.	Espera los segundos de `Retry-After` y reintenta con retroceso exponencial. Lee `RateLimit-Remaining` para frenar antes. Mira Límites de uso.
`429 RATE_DDOS_EXCEEDED`	Demasiadas peticiones desde la misma IP, o la IP quedó cortada 15 minutos por probar muchas claves distintas que no autentican.	Espera lo que diga `Retry-After`. Si usas varias claves detrás de la misma salida a internet, revisa que ninguna esté mal copiada o eliminada.
`429 URLSHORTENER_LINK_QUOTA_EXCEEDED`	Con un plan del acortador, llegaste al cupo diario de altas.	`Retry-After` dice cuánto falta para la medianoche de Colombia. Si necesitas más, escribe a comercial.

No me deja crear

Saldo, plan y moneda
Qué ves	Causa más común	Qué hacer
`402 URLSHORTENER_INSUFFICIENT_FUNDS`	Tu organización no tiene saldo disponible para crear el enlace. No se creó.	Recarga el saldo en Cloud y reintenta, mejor con la misma `Idempotency-Key`.
`402 URLSHORTENER_SPEND_LIMIT_REACHED`	Crear el enlace superaría un tope de gasto que tu organización configuró.	Recargar no lo resuelve: ajusta el tope en Cloud.
`409 URLSHORTENER_CURRENCY_UNDEFINED`	Tu organización todavía no eligió su moneda.	Elígela en Cloud (se elige una sola vez).
`409 URLSHORTENER_NOT_PRICED`	No hay tarifa del acortador en la moneda de tu organización.	Reintentar no lo arregla. Escribe a soporte con el `requestId`.

Mi petición no es válida

Peticiones mal formadas
Qué ves	Causa más común	Qué hacer
`400 VALIDATION_INVALID_PARAMETER`	Un campo con formato inválido, un campo que no existe (por ejemplo `url` o `alias`, del contrato anterior) o un JSON mal formado.	Compara tu cuerpo con la página del endpoint en la referencia. El mensaje nombra el campo.
`400 URL_INVALID`, `URL_SCHEME_NOT_ALLOWED`, `URL_BLOCKED_HOST`	El destino no es una URL absoluta `http` o `https`, apunta a una dirección interna o ya es un enlace corto.	Usa una URL pública completa. Mira la guía del Acortador de URLs.
`409 ALIAS_TAKEN`, `ALIAS_RESERVED`, `ALIAS_RETIRED`	El alias ya existe en ese dominio, es una palabra reservada o una marca en un dominio compartido, o fue el de un enlace tuyo eliminado.	Elige otro alias, o restaura el enlace eliminado si era tuyo.
`422 IDEMPOTENCY_KEY_REUSED`	Usaste una `Idempotency-Key` con un cuerpo distinto al de la primera vez.	Una llave identifica una operación: usa una llave nueva. Mira Idempotencia.
`404 NOT_FOUND`	La ruta no existe: un error de escritura en el camino, otra versión o un endpoint que no está en la referencia.	Revisa que llamas a `https://developers.hablame.co/api/v6/...` y que el camino coincide con la referencia.
`501 NOT_IMPLEMENTED`	La ruta está reservada pero todavía no tiene un servicio detrás.	No reintentes. Usa solo los endpoints de la referencia.
`405 METHOD_NOT_ALLOWED`	Usaste un método que la ruta no admite. Las consultas de Almacenamiento son solo `GET`.	Usa el método que indica la referencia.

Falla de nuestro lado

Fallos del servicio
Qué ves	Causa más común	Qué hacer
`503 SERVICE_UNAVAILABLE`	Un servicio del que dependemos no responde, o está atendiendo demasiadas peticiones a la vez y rechaza la tuya al instante.	Reintenta tras `Retry-After` con un margen aleatorio. Si persiste, mira el estado.
`504 GATEWAY_TIMEOUT`, `INFRA_DB_QUERY_TIMEOUT`	Un servicio tardó demasiado, por ejemplo en una consulta muy amplia.	Reintenta con retroceso exponencial y, si puedes, acota el rango de fechas o el filtro.
`500 INTERNAL_SERVER_ERROR`	Algo salió mal de forma inesperada de nuestro lado.	Reintenta una vez. Si se repite, escribe a soporte con el `requestId`.

En un 5xx al crear un enlace, reintenta siempre con la misma Idempotency-Key: así, si la primera sí llegó a crearse, recibes ese enlace y no se cobra dos veces.

El producto no se comporta como espero

El enlace corto da 404: Un enlace active deja de redirigir si pasó su expiresAt, si su dominio está suspendido, liberado o sin verificar (domainStatus), o si Hablame lo bloqueó (status: blocked). Consulta el enlace con GET /urlshortener/links/{domain}/{code}.
Las visitas no coinciden: Un proceso en segundo plano consolida las visitas: una puede tardar de segundos a pocos minutos en aparecer. No se cuentan robots ni las vistas previas de redes sociales y chats.
No me llegan los webhooks: Revisa que tu URL responda con un código 2xx y no use redirecciones, y que verificas la firma sobre el cuerpo sin modificar. Mira Entrega y reintentos.
Mi cliente se rompe con un campo nuevo: La API añade campos sin avisar; los existentes no cambian de tipo. Tu cliente debe ignorar lo que no conoce. Mira la envoltura de respuesta.
Llamo desde el navegador: No lo hagas con tu clave real: cualquiera que abra las herramientas del navegador la vería. Haz la llamada desde tu servidor.

Qué reunir antes de escribir a soporte

El meta.requestId de la respuesta (también está en la cabecera X-Request-Id). Es lo más útil: con él encontramos tu petición exacta.
El error.code y el código HTTP.
El endpoint y el método que llamabas, y la hora en UTC.
El nombre de tu organización.

No envíes tu clave de API completa, una contraseña SMPP ni un secreto de firma. Para identificar tu cuenta basta el nombre de tu organización.

Para dudas técnicas escribe a developers@hablame.co. Si tienes una incidencia en producción, escribe por WhatsApp al +57 319 660 0002, las 24 horas.