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ó.

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.

Tu IP de origen produjo un volumen inusualmente alto de peticiones en el último minuto. Esta protección está pensada para absorber tráfico de ataque y de escáneres; las integraciones legítimas rara vez se acercan al límite.

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.

La Idempotency-Key está vacía, es demasiado larga o trae caracteres fuera del conjunto permitido. Se aceptan de 1 a 255 caracteres de A-Z a-z 0-9 _ -.

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 ya existe, con un cuerpo diferente. Casi siempre es un error del cliente: una llave identifica una operación, no varias.

La url que enviaste no es una URL absoluta válida: no pudimos extraer un esquema y un host.

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). Los bloqueamos para que los enlaces cortos no sirvan para alcanzar destinos internos.

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

Otro enlace del mismo dominio ya usa ese alias. Los códigos son únicos por dominio.

El alias choca con una palabra reservada (por ejemplo api, stats, admin o docs).

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 (active, expiresAt, longUrl).

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

La ventana de estadísticas es inconsistente: from posterior a to, un rango mayor al tope (1 año para day, 31 días para hour), o granularidad hour pedida fuera de los últimos 90 días.

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

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