---
title: "Manejo de Errores"
description: "Aprende a identificar y resolver errores al usar API Gateway"
type: "academy"
category: "lesson"
tags: []
authors: [Anonymous]
date: "2026-08-27"
last_update: "2026-08-21"
time_minutes: 5
draft: false
unlisted: false
url: "https://www.stage.apigateway.cl/academy/capacitacion-inicial/primeros-pasos/manejo-de-errores"
---

# Manejo de Errores

Los errores son parte normal del desarrollo. Lo importante es saber identificarlos rápidamente y entender qué significan. Swagger UI facilita mucho este proceso al mostrar toda la información de manera visual.

---

## Códigos de Error Principales

### Tabla de Referencia Rápida

| Código | Nombre | Significado | Acción Requerida |
|--------|--------|-------------|------------------|
| **400** | Bad Request | Petición inválida o falla al ser procesada (error genérico). | Revisar JSON/parámetros |
| **401** | Unauthorized | Access Token incorrecto, credenciales SII incorrectas o problema con la sesión del SII. | Verificar token o credenciales |
| **402** | Payment Required | El período de prueba terminó y se debe pasar a un plan de pago. | Actualizar suscripción |
| **403** | Forbidden | No tiene autorización para acceder al recurso solicitado. | Verificar alcance del token |
| **404** | Not Found | Recurso solicitado no pudo ser encontrado. | Revisar URL/parámetros |
| **405** | Method Not Allowed | El método o acción solicitada no está permitida en el recurso. | Revisar método HTTP |
| **406** | Not Acceptable | Solicitó la respuesta en un formato de datos incorrecto. | Revisar formato de respuesta |
| **409** | Conflict | Solicitud no pudo ser procesada debido a conflicto con el origen de los datos en el SII. | Revisar datos |
| **410** | Gone | El recurso solicitado ya no existe en nuestra API. | Revisar URL/parámetros |
| **423** | Locked | La cuenta fue bloqueada por incumplir términos y condiciones. | Contactar soporte |
| **429** | Too Many Requests | Se alcanzó el límite de la cuota, se debe dejar de hacer consultas hasta que se renueven. | Esperar o revisar headers |

> [!NOTE] Nota
>
>Con el paso del tiempo podríamos ir agregando o eliminando tipos de errores. Se recomienda verificar que la aplicación se adapte a estos cambios o al menos maneje un caso por defecto cuando hay un error que no conoce.

---

## Bloqueo de la cuenta

API Gateway tiene [términos y condiciones](https://www.apigateway.cl/legal) que norman el uso. En estos términos hay 2 condiciones que pueden llevar a un bloqueo de la cuenta:

- Compartir IP.
- Tener muchas consultas con código de respuesta HTTP 429.

Ambos puntos se explican en los términos y condiciones de API Gateway.

Este bloqueo no puede ser removidor por el equipo de soporte. Por lo que:

- Deberás esperar a que se desbloqueen las consultas.
- Contratar un plan con más consultas.

---

## Identificando Errores

### Ubicación de la Información

Cuando ocurre un error, encontrarás:

1. **Status Code**: En la parte superior de la respuesta
2. **Response Body**: El mensaje de error en JSON
3. **Response Headers**: Información adicional importante

### Ejemplo Visual de Error 401

```
Response
Code: 401
Details: Error: Unauthorized

Response body:
{
  "code": 401,
  "message": "Token de acceso inválido o expirado"
}

Response headers:
content-type: application/json
x-request-id: 123e4567-e89b-12d3-a456-426614174000
```

---

## Interpretando Headers de Respuesta

### Headers de Rate Limiting

Estos headers aparecen en **TODAS** las respuestas:

| Header | Significado | Ejemplo |
|--------|-------------|---------|
| `X-RateLimit-Limit` | Máximo de peticiones permitidas cada 24 horas | 1000 |
| `X-RateLimit-Remaining` | Peticiones restantes | 847 |

> **Nota**: Se recomienda hacer uso de estas cabeceras para monitorear el uso de la API. Con esto evitarás que se bloqueen tus consultas, una vez que llegues al límite.

### Headers cuando llegas al límite

| Header | Significado | Ejemplo |
|--------|-------------|---------|
| `Retry-After` | Segundos hasta poder reintentar | 3600 |
| `X-RateLimit-Reset` | Timestamp cuando se resetea | 1640995200 |

## Errores Comunes y Soluciones

### Error 401: Unauthorized

**Variante 1: Token API inválido**
```json
{
  "message": "Unauthenticated."
}
```
**Solución**:
- Verifica que el token esté en Authorization: Bearer
- Regenera el token si es necesario

**Variante 2: Credenciales SII incorrectas**
```json
{
  "code": 401,
  "message": "Autenticación con SII falló: clave incorrecta"
}
```
**Solución**:
- Verifica RUT y clave
- Prueba en el sitio del SII directamente

**Variante 3: Sesión SII expirada**
```json
{
  "code": 401,
  "message": "Se debe volver a autenticar al usuario en la sesión del SII."
}
```
**Solución**:
- Agrega `?auth_cache=0` para forzar nueva sesión


### Error 429: Too Many Requests

```json
{
  "message": "Too Many Attempts."
}
```

**Información en headers**:
```
Retry-After: 3600
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
```

**Solución**:
1. **Lee** el header `Retry-After`
2. **Espera** ese tiempo (en segundos)
3. **Opcional**: Revisa tu plan para más cuota

### Error 400: Bad Request

```json
{
  "code": 400,
  "message": "El campo 'rut' es requerido"
}
```

**Causas comunes**:
- JSON mal formateado
- Campos requeridos faltantes
- Tipos de datos incorrectos

**Cómo debuggear en Swagger**:
1. Revisa el JSON en el editor
2. Verifica que no falten comillas
3. Usa la validación de Swagger (marca errores en rojo)

---

## Estrategias de Prevención

### 1. Monitoreo de Rate Limit

**En cada respuesta exitosa**, revisa:
```
X-RateLimit-Remaining: 150
```

Si es menor a 100, considera:
- Espaciar las consultas
- Implementar caché local
- Optimizar las llamadas

### 2. Manejo de Sesiones SII

**Problema**: El header `X-Stats-NavegadorSessionProblem: 1`

**Prevención**:
- No abuses del `auth_cache=0`
- Deja expirar sesiones naturalmente (2 horas)

### 3. Validación Previa

Antes de enviar:
- Revisa que el JSON esté bien formateado
- Verifica que todos los campos requeridos estén presentes
- Confirma que los tipos de datos sean correctos


---
Last updated on 21/08/2026