Catálogo de errores

No vimos un token Bearer en tu petición. Cada llamada a la API v6 necesita una clave de API en el header Authorization: sin ella no podemos saber qué organización está consultando.

La clave de API que enviaste no se reconoce. Tres situaciones producen este código: una clave con el formato equivocado, una clave que fue rotada o revocada, o una clave que ya pasó su fecha de vencimiento.

Cada clave de API está asociada a un centro de costo para que el uso se facture y se reporte correctamente. El centro de costo de esta clave está deshabilitado.

Esta clave no tiene permitido llamar al servicio detrás de este endpoint. Las claves se restringen a servicios específicos para que una clave filtrada o mal usada solo pueda hacer aquello que se le permitió. Cada servicio se da completo: con el acortador, la clave también crea y borra enlaces; con Almacenamiento, también ve y descarga los archivos. Sin el servicio, la clave no puede usar ninguno de sus endpoints.

Los endpoints de cuenta y de organización exigen una capacidad concedida de forma explícita: account (saldo y facturación) o directory (datos de la organización, centros de costo y usuarios). Son las únicas capacidades: dentro de un servicio no hay permisos parciales, porque el servicio se da completo.

Esta clave tiene una lista de redes permitidas (IPs sueltas o bloques CIDR, IPv4 o IPv6) y la petición llegó desde una IP que no está en ninguna. La clave es válida y tu organización está activa: lo único que no coincide es el origen. La IP con la que te vimos viene en meta.clientIp de la misma respuesta.

Código reservado, se mantiene como puente para quienes vienen migrando desde v5. La API v6 no usa el mecanismo de sustitución de IP de origen que producía este error, así que no deberías verlo en tráfico v6.

Tu organización no está en estado activo, normalmente porque fue suspendida o cerrada. Mientras siga así, todos los endpoints rechazan las llamadas, incluso los de diagnóstico.

Tu organización tiene un bloqueo total. Cada llamada se rechaza, incluidas las de solo lectura, hasta que se retire el bloqueo.

Tu organización está en modo solo lectura. Las peticiones que solo consultan información (GET, HEAD, OPTIONS) siguen funcionando, pero cualquier llamada que cree o modifique datos se rechaza.

Tu clave de API se autenticó bien, pero no pudimos cargar la organización a la que apunta. Es un problema de datos de nuestro lado, no de tu petición.

La protección por IP de origen se disparó, por una de dos razones. La primera: tu IP produjo un volumen inusualmente alto de peticiones en el último minuto; las integraciones legítimas rara vez se acercan al límite. La segunda: desde tu IP llegaron 60 API keys distintas que no autentican en un minuto (que no existen, o que fueron revocadas o vencieron), que es la huella de quien prueba claves al azar; entonces la IP queda cortada 15 minutos y en ese tiempo recibe este 429, aunque la clave que envíes sea válida. Las dos cuentan las direcciones IPv6 por su bloque /64: todas las direcciones de un mismo /64 comparten el tope y el corte.

Enviaste más peticiones a este endpoint de las que permite el cupo de tu organización en la ventana actual. Cada endpoint tiene su propio cupo: chocar con la pared en uno no afecta a los demás. En el resumen y las estadísticas del acortador hay además un cupo por costo: cada consulta gasta unidades según los días y las secciones que pide, y el resumen se calcula como mucho dos veces a la vez por organización. Y el alta en lote del acortador tiene un límite por enlaces (2.100 por minuto por organización): un lote que no cabe se rechaza entero, sin crear ni cobrar nada.

La Idempotency-Key es demasiado larga o trae caracteres fuera del conjunto permitido. Se aceptan de 1 a 255 caracteres de A-Z a-z 0-9 _ -. No se hizo nada: ni se creó ni se cobró.

Enviaste la misma llave de idempotencia mientras la petición original todavía se está procesando. No se ejecuta dos veces: la segunda espera.

Usaste una llave de idempotencia que tu organización ya usó, con un cuerpo diferente. No se creó nada nuevo ni se cobró. Casi siempre es un error del cliente: una llave identifica una operación, no varias.

La URL de destino no es una URL absoluta válida (no pudimos extraer un esquema y un host), o trae algo que haría que quien la lea vea un destino distinto del real: un usuario o una clave antes del dominio (https://banco.com@otro.com), un dominio con tildes, eñes o letras de otros alfabetos (también escrito en xn--), o caracteres invisibles. El message dice cuál de estos fue.

El destino usa un esquema que no acortamos (por ejemplo javascript:, data:, ftp: o file:).

La URL de destino es más larga que el máximo de 2048 caracteres.

El destino apunta a una dirección privada o reservada, o a un nombre de host interno (por ejemplo 127.0.0.1, 10.0.0.0/8 o localhost), o ya es un enlace corto: uno de nuestros dominios o un acortador como bit.ly, tinyurl.com o t.co. Los bloqueamos para que los enlaces cortos no sirvan para alcanzar destinos internos ni para esconder el destino final detrás de una cadena de saltos.

El alias no tiene entre 3 y 32 caracteres de minúsculas, dígitos, guion o guion bajo.

Ese alias ya lo usó otro enlace del mismo dominio, exista hoy o no: los enlaces eliminados o vencidos hace 90 días o más se archivan, y su código sigue reservado para siempre. Los códigos son únicos por dominio y no se liberan nunca.

El alias choca con una palabra reservada (por ejemplo api, stats, admin o docs), o (en un dominio de la plataforma, que comparten todas las organizaciones) se parece al nombre de una marca, un banco, un medio de pago o una entidad pública (bancolombia-seguro, pago-pse, dian). Un solo enlace de suplantación en un dominio compartido hace que los filtros de seguridad lo marquen, y entonces dejan de abrir los enlaces de todos.

expiresAt no se pudo interpretar como fecha y hora ISO-8601, o está en el pasado.

Ningún enlace con ese dominio y código pertenece a tu cuenta. Por privacidad también devolvemos 404 para enlaces de otras cuentas, así no se revela su existencia.

El cuerpo del PATCH no traía ninguno de los campos actualizables (longUrl, status, expiresAt).

No pudimos asignar un código aleatorio único después de varios intentos. Es poco frecuente.

La ventana de estadísticas no es válida: from o to no tienen la forma AAAA-MM-DD, from es posterior a to, la ventana supera el tope (366 días con day, 31 días con hour) o la granularidad no es day ni hour.

El domain que pediste no es un dominio global de la plataforma ni uno de tu cuenta, o tu cuenta no tiene un dominio predeterminado configurado.

El domain es uno propio de tu organización, pero todavía no está verificado. Mientras no lo esté no sirve para crear enlaces: podría no apuntar aún a la plataforma, y el enlace nacería roto.

Ese alias ya lo usaste en un enlace que eliminaste. El código de un enlace eliminado no se libera nunca (una URL corta que ya repartiste no puede reaparecer con otro destino), así que no se puede crear otro enlace con él. Pero ese enlace se puede restaurar durante 90 días desde que lo eliminaste; después se archiva y el alias responde ALIAS_TAKEN.

Hablame bloqueó este enlace (status: blocked), por ejemplo por un reporte de suplantación. Un enlace bloqueado no redirige y no se puede editar, eliminar ni restaurar desde la API.

Con un plan del acortador vigente, crear enlaces no se cobra, y por eso hay un cupo de altas por día de Colombia (100.000, salvo que tengas otro pactado). Tu organización ya lo usó hoy, o el lote que mandaste no cabe en lo que le queda: en el alta en lote cuenta cada enlace, y un lote que no cabe entero se rechaza entero, sin crear ninguno. Sin plan no hay cupo diario: lo que frena es el saldo.

El alta en lote admite hasta 1.000 enlaces por petición, y el que mandaste trae más. No se creó ninguno ni se cobró nada.

Crear un enlace se cobra al crearlo, y tu organización no tiene saldo disponible para cubrirlo (o alcanzó un tope de gasto que ella misma configuró). El enlace no se creó. En el alta en lote se reserva el precio de todos los enlaces válidos a la vez: sin saldo para todos, no se crea ninguno.

Tu organización tiene saldo, pero crear este enlace superaría un tope de gasto que ella misma configuró: para toda la organización, para el acortador, para un centro de costo, para un usuario o para esta clave de API. El enlace no se creó.

No encontramos una tarifa del acortador para la moneda de tu organización, así que no podemos cobrar la operación y no la hacemos. Es un problema de configuración de nuestro lado, no de tu petición.

La moneda de una organización se elige una sola vez, al terminar de configurarla, y todo lo que consume se cobra en ella. Mientras no la tenga, no podemos ponerle precio a la operación y no la hacemos.

No hay un archivo con ese id que tu organización pueda ver. Es la MISMA respuesta, a propósito, para un archivo que nunca existió, uno de otra organización, uno ya eliminado o que se está eliminando, y un id mal formado: así no se puede averiguar qué archivos existen probando identificadores.

El cursor está alterado, es de otra organización, se pidió con otros filtros o tiene más de 24 horas. Un cursor solo sirve para seguir el MISMO listado, con los mismos filtros, por poco tiempo.

Un servicio o un tipo de archivo que no existe, un scope sin service, una fecha que no se entiende, un rango al revés o demasiado largo (hasta 400 días por día o mes, hasta 7 días por hora), un group distinto de day, month u hour, un limit fuera de 1 a 200 o unos minutes fuera de 1 a 60. El mensaje dice cuál, en español, con el nombre interno del parámetro (desde es from, hasta es to, agrupar es group, limite es limit).

Quitamos del número todo lo que no sea un dígito (espacios, guiones o el signo +) y contamos lo que queda: tiene que haber entre 7 y 18 dígitos. Fuera de ese rango no hacemos la llamada ni cobramos nada. El servicio de llamadas automáticas todavía no está abierto en la referencia pública; el código está documentado para que su enlace en error.type lleve a esta explicación.

El código de verificación lo generas tú, y Hablame no lo inventa: tiene que venir en la petición, porque es el mismo que tu sistema va a comparar después con lo que escriba la persona. Sin él no se hace la llamada ni se cobra nada.

El código que se dicta por llamada solo admite dígitos y hasta 10. Una letra, un espacio o un código más largo se rechazan antes de llamar.

En el mensaje, {otp} marca el lugar donde se dicta el código. Con dos marcadores no hay forma de saber cuál querías, y dictar el código dos veces es peor que no llamar, así que rechazamos el mensaje.

La voz necesita un texto para decir, de 1 a 4.000 caracteres. Un mensaje vacío o más largo se rechaza antes de llamar.

Antes de llamar reservamos lo que la llamada puede costar. Si tu organización no tiene saldo disponible, o no tiene una cuenta de facturación activa, la llamada no se hace y no se cobra nada. El nombre incluye TTS porque es el mismo código que ya existía para el saldo que falta al generar la voz de una llamada.

No marcamos sin saber cuánto cuesta. Si no hay una tarifa para el destino de la llamada, no se hace y no se cobra nada. Es un problema de configuración de nuestro lado, no de tu petición.

El saldo se reserva en una moneda y se cobra en la misma. Si la tarifa del destino viene en otra distinta a la de tu organización, rechazamos la llamada en lugar de convertir entre monedas. No se hace la llamada y no se cobra nada.

El código enviado a GET /api/v6/tools/countries/{code} no corresponde a ningún país del catálogo. El parámetro espera un ISO 3166-1 alpha-2 de dos letras.

Uno de los servicios de los que dependemos estaba temporalmente inalcanzable cuando llegó tu petición. Es un problema de nuestro lado, no de lo que enviaste.

Mismo escenario que el anterior, con otra pieza interna. La falla es transitoria y se recupera de nuestro lado sin cambios del tuyo.

Una consulta interna tomó más tiempo del que permitimos antes de devolver una respuesta, así que la cortamos en vez de dejar a tu cliente esperando de forma indefinida. En el acortador (la lista de enlaces, sus estadísticas y el resumen) la corta la propia base de datos, y pasa con consultas muy grandes para organizaciones con muchos enlaces: un rango largo, muchas secciones o una búsqueda amplia.

Un parámetro de la consulta tiene un valor que no existe, o el cuerpo trae un campo desconocido, un tipo equivocado o no es JSON. El message dice cuál y qué valores acepta.

No pudimos interpretar tu petición. Las causas más comunes son JSON mal formado en el cuerpo, un header Content-Type que no coincide con el contenido, o una ruta con caracteres inválidos.

401 genérico devuelto antes de que la lógica de autenticación pudiera darte un código más específico. Cuando ves este código, la petición se rechazó en una capa anterior a la validación de la clave de API.

La petición se autenticó bien, pero no tiene permitido acceder a este recurso. Cuando la causa es un estado conocido de la organización recibes un código ACCOUNT_*; este genérico es la alternativa.

La ruta que pediste no existe en esta API. También devolvemos este código, de forma deliberadamente indistinguible de un 404 normal, para peticiones cuyo header Host no está en nuestra lista permitida, así la superficie de la API no se puede sondear adivinando nombres de host.

La ruta existe pero no acepta el método HTTP que usaste, por ejemplo un POST a un endpoint de solo lectura. La respuesta incluye un header Allow con los métodos válidos.

El servicio que atiende la ruta respondió 409 Conflict sin un código propio, así que la respuesta lleva este genérico. Los conflictos que conocemos tienen su código específico, como ALIAS_TAKEN o DOMAIN_NOT_VERIFIED: ramifica sobre esos cuando estén. El message trae la explicación del servicio cuando la envía; si no, un texto general que remite a esta página.

El servicio que atiende la ruta respondió 422 Unprocessable Entity sin un código propio, así que la respuesta lleva este genérico. Los casos que conocemos tienen su código específico, como IDEMPOTENCY_KEY_REUSED: ramifica sobre esos cuando estén. El message trae la explicación del servicio cuando la envía; si no, un texto general que remite a esta página.

429 genérico. Cuando el límite que tocaste es uno nuestro devolvemos RATE_DDOS_EXCEEDED o RATE_TPS_EXCEEDED, que traen más contexto. Ramifica sobre los específicos cuando estén presentes.

La ruta está reservada en la API, pero todavía no tiene un servicio detrás que la atienda. El mensaje de la respuesta dice por qué. No es un fallo temporal ni un error de tu petición.

Algo salió mal de forma inesperada mientras procesábamos tu petición. La traza completa queda guardada contra el mismo meta.requestId que te devolvimos, así podemos investigar sin que tengas que reproducir la falla.

El servicio que atiende la ruta respondió 502 Bad Gateway sin un código propio, así que la respuesta lleva este genérico. La falla está de nuestro lado, no en tu petición. El message trae la explicación del servicio cuando la envía; si no, un texto general que remite a esta página.

Un servicio del que dependemos no está respondiendo, o está atendiendo demasiadas peticiones a la vez: cada servicio tiene su propio cupo de peticiones simultáneas en el borde, y cuando se llena la petición se rechaza al instante con Retry-After en vez de quedarse esperando. Los códigos INFRA_* son más específicos cuando podemos nombrar el componente que falló; este es la alternativa cuando no.

Un servicio del que dependemos tardó demasiado en responder. Cuando el componente lento fue la base de datos verás INFRA_DB_QUERY_TIMEOUT, que significa lo mismo con más contexto.