Catálogo de errores

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

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

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

Esta key no tiene permitido llamar al servicio detrás de este endpoint. Las keys se pueden restringir a servicios específicos para que una key filtrada o mal usada solo pueda hacer aquello que se le permitió.

Algunos endpoints exigen, además del servicio, una capacidad concedida de forma explícita. En el acortador, crear, editar, borrar y restaurar enlaces exige urlshortener.write: una key con el servicio urlshortener y sin esa capacidad lista y consulta enlaces, estadísticas, el resumen, los dominios y la tarifa, y al intentar escribir recibe este código. Los endpoints de cuenta y de organización exigen account o directory, y ahí el mensaje es otro: «This API key lacks the capability required for this endpoint. Capabilities are set when a key is issued and cannot be added later: use a key that has it, or issue a new one that includes it from the customer portal (Developers -> API keys).»

Esta key 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 key 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 API key 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 keys al azar; entonces la IP queda cortada 15 minutos y en ese tiempo recibe este 429, aunque la key 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.

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 API key.

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.

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.

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.

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.