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

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

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

Errores Comunes y Soluciones

Error 401: Unauthorized

Variante 1: Token API inválido

{
  "message": "Unauthenticated."
}

Solución:

• Verifica que el token esté en Authorization: Bearer
• Regenera el token si es necesario

Variante 2: Credenciales SII incorrectas

{
  "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

{
  "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

{
  "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

{
  "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