---
title: "Errores 401 al consumir la API"
description: "Diagnóstico de los distintos 401: token inválido, cabecera mal formada, credenciales del SII y sesión caída."
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-11"
last_update: "2026-09-11"
time_minutes: 3
draft: false
unlisted: false
url: "https://www.apigateway.cl/docs/solucion-de-problemas/errores-de-autenticacion-en-la-api"
---

# Errores 401 al consumir la API

El `401` agrupa cuatro problemas distintos. El mensaje del campo `detail` te dice cuál es.

## "Las credenciales de autenticación no se proveyeron"

Falta la palabra `Token` en la cabecera. La API **no acepta** `Bearer`, ni `X-Api-Key`, ni el token en la URL:

```http
Authorization: Token 0123456789abcdef0123456789abcdef01234567   ← correcto
Authorization: Bearer 0123456789abcdef0123456789abcdef01234567  ← incorrecto
Authorization: 0123456789abcdef0123456789abcdef01234567         ← incorrecto
```

## "Token de conexión inválido"

El token no corresponde a ninguna conexión activa. Revisa en orden:

1. **Compáralo carácter por carácter** con el de [Gestionar conexión → Token](https://app.apigateway.cl/connections/manage#token). En la mayoría de los casos el token de la integración quedó desactualizado o se cargó en el lugar equivocado del código.
2. **¿Lo regeneraste?** El anterior deja de funcionar de inmediato.
3. **¿Es el token de la conexión** y no la API Key de tu usuario?
4. **¿Estás usando la plataforma correcta?** El token de V2 no funciona en Legacy.
5. **¿La URL base es la correcta?** `https://app.apigateway.cl/api/v2/`, no `apigateway.cl`.

## "La conexión está inactiva"

El token está bien: la conexión está **suspendida**. Revisa [Créditos y conexión suspendida](https://www.apigateway.cl/docs/solucion-de-problemas/creditos-y-conexion-suspendida).

## Credenciales del SII incorrectas

Cuando el `401` incluye un código de error del propio SII:

```json
{
  "detail": "En la respuesta del SII se obtuvo el código de error #612. Descripción del error oficial del SII: Contraseña incorrecta."
}
```

el problema está en las credenciales que envías en el cuerpo, no en la plataforma.

1. **Verifica la clave** ingresando directamente a [www.sii.cl](https://www.sii.cl).
2. **Verifica el formato del RUT**: sin puntos, con guión, `11111111-1`. Un RUT con puntos puede producir errores que parecen de otra naturaleza, incluidos timeouts de navegación.
3. **Verifica la estructura de `auth`**: debe ser exactamente `auth.pass.rut` y `auth.pass.clave`.
4. **Si cambiaste la clave recientemente**, actualízala en tu integración y fuerza una sesión nueva con `auth_cache=0` en la primera consulta.

## "Se debe volver a autenticar al usuario en la sesión del SII"

La sesión reutilizada quedó en mal estado. Puede venir acompañado de la cabecera `X-Auth-Session-Problem: 1`.

Agrega `auth_cache=0` a la URL en esa consulta, y vuelve a operar sin el parámetro después.

> [!WARNING] No lo dejes puesto en producción
>
> Cada `auth_cache=0` equivale a un login nuevo en el SII. Usarlo en todas las peticiones aumenta el riesgo de que el SII bloquee tus accesos.

## 401 en un recurso específico, mientras otros funcionan

Si un recurso devuelve `401` de forma reproducible y otros funcionan con las mismas credenciales, revisa el **método de autenticación que ese recurso requiere**. Algunos exigen certificado digital y no RUT y clave.

Un caso real: `bienes_raices/propiedades/contribuyente` devolvía `401` en contribuyentes con muchos roles inmobiliarios al consultarlo con RUT y clave. Ese recurso requiere **certificado digital**.

Revisa [Token y certificado](https://www.apigateway.cl/docs/manual/token-y-certificado) y la documentación del recurso en [/docs/api](https://www.apigateway.cl/docs/api).



---
Última actualización el 11/09/2026