Manejo de Errores

GitLab MCP Server proporciona un manejo de errores estructurado que clasifica los errores, extrae detalles accionables de las respuestas de la API de GitLab y sugiere acciones correctivas al asistente de IA.

Clasificación de errores

Cada error de la API de GitLab se clasifica por código de estado HTTP en un mensaje accionable:

| Código de Estado | Clasificación | Mensaje | | ---------------- | -------------------- | ---------------------------------------------------- | | 400 | Solicitud incorrecta | Verifica tus parámetros de entrada | | 401 | Autenticación | GITLAB_TOKEN puede ser inválido o haber expirado | | 403 | Permisos | Tu token carece de los permisos requeridos | | 404 | No encontrado | El recurso no existe o no tienes acceso | | 409 | Conflicto | El recurso ya existe o hay un conflicto de estado | | 422 | Validación | GitLab rechazó la solicitud debido a datos inválidos | | 429 | Límite de velocidad | Demasiadas solicitudes — espera antes de reintentar | | 500 | Error del servidor | Error interno del servidor de GitLab | | 502 | Bad gateway | GitLab está temporalmente no disponible | | 503 | Mantenimiento | GitLab está en mantenimiento o sobrecargado |

Los errores a nivel de red también se clasifican:

| Tipo de Error | Mensaje | | ------------------ | ---------------------------------------------------- | | Conexión rechazada | El servidor de GitLab es inaccesible | | Fallo DNS | No se pudo resolver el nombre del servidor de GitLab | | Timeout | La solicitud a GitLab excedió el tiempo de espera | | TLS/SSL | El handshake TLS/SSL falló |

Funciones de envoltura de errores

El servidor usa tres funciones de envoltura de errores, elegidas según el tipo de operación:

Usada para operaciones list, get y search. Clasifica el error y lo envuelve con el nombre de la operación:

list_issues: authentication failed — GITLAB_TOKEN may be invalid or expired

Usada para operaciones create, update y delete. Incluye el detalle específico del error extraído de la respuesta de la API de GitLab:

fileCreate: bad request — A file with this name already exists: POST .../files: 400

El servidor extrae el mensaje de error detallado de la respuesta de la API de GitLab, manejando formatos anidados como {message: {base: [text]}}, y trunca a 300 caracteres.

Usada cuando se conoce la acción correctiva para un error específico. Añade una sugerencia accionable:

branchProtect: conflict — Protected branch rule already exists.
Suggestion: use gitlab_protected_branch_get to view current rules

Árbol de decisión

| Escenario | Función | | ----------------------------------------------- | ----------------------- | | Operación de solo lectura (list, get, search) | WrapErr | | Operación de escritura (create, update, delete) | WrapErrWithMessage | | Error específico con corrección conocida | WrapErrWithHint | | Hint específico para un código de estado | WrapErrWithStatusHint | | Operación get que devuelve 404 | NotFoundResult |

flowchart TD
    A[Operación] --> B{Tipo?}
    B -->|Solo lectura| C[WrapErr]
    B -->|Escritura| D{Hint conocido?}
    D -->|No| E[WrapErrWithMessage]
    D -->|Sí| F{Código específico?}
    F -->|Sí| G[WrapErrWithStatusHint]
    F -->|No| H[WrapErrWithHint]
    B -->|GET 404| I[NotFoundResult]

    style C fill:#3b82f6,color:#fff
    style E fill:#f59e0b,color:#000
    style G fill:#ef4444,color:#fff
    style H fill:#ef4444,color:#fff
    style I fill:#22c55e,color:#fff

NotFoundResult — Respuestas informativas para 404

Para los handlers de tipo get, los errores 404 se tratan como informativos en lugar de fallos. En vez de devolver un error Go opaco (registrado a nivel ERROR), el handler devuelve un CallToolResult con IsError: true y sugerencias específicas del dominio:

## ❓ Branch Not Found

Branch `feature/old` was not found in the project.

💡 **Next steps:**

- Use `gitlab_list_branches` to see available branches
- Check branch name spelling and case sensitivity

Este patrón se aplica a los 27 handlers get en 21 dominios. Se registra a nivel INFO (resultado esperado) y proporciona al asistente de IA los siguientes pasos accionables.

Sugerencias de validación

Para errores de validación 422, el servidor enriquece automáticamente el error con guía basada en coincidencia de patrones. Se reconocen más de 15 patrones comunes, incluyendo:

Campos requeridos faltantes
Formatos de fecha inválidos
Límites de longitud de nombre/título
Nombres de recursos duplicados
Valores de enumeración inválidos

Estas sugerencias ayudan al asistente de IA a corregir su solicitud sin llamadas adicionales a la API.

Formato de respuesta de error

Cuando una herramienta encuentra un error, la respuesta se formatea como un bloque Markdown con campos de diagnóstico estructurados:

## ❌ Error: list_branches

**Status**: 401 Unauthorized
**Detail**: authentication failed — GITLAB_TOKEN may be invalid or expired
**Request ID**: abc123def456

💡 **Suggestion**: Check that your token is valid and has the `api` scope.

La respuesta estructurada incluye:

| Campo | Descripción | | -------------- | ------------------------------------------------ | | Operation | La acción de la herramienta que falló | | Status | Código de estado HTTP y clasificación | | Detail | Mensaje de error específico de GitLab | | Request ID | X-Request-Id de GitLab para tickets de soporte | | Suggestion | Sugerencia accionable (cuando está disponible) |

Errores transitorios vs permanentes

El servidor clasifica los errores como transitorios (reintentables) o permanentes:

| Tipo | Códigos de Estado | Comportamiento | | ----------- | -------------------------------------- | --------------------------------------------------- | | Transitorio | 429, 5xx, timeouts, conexión rechazada | Seguro reintentar después de una espera | | Permanente | 4xx (excepto 429) | No reintentar — corregir la entrada o configuración |

Ejemplos de escenarios de error

Token inválido

❌ list_projects: authentication failed — GITLAB_TOKEN may be invalid or expired
💡 Generate a new token with api scope at GitLab → Preferences → Access Tokens

Permiso denegado

❌ create_issue: access denied — your token lacks the required permissions
Detail: 403 Forbidden
💡 Ensure the token has api scope and you have Developer+ access to the project

Conflicto de recurso

❌ branchProtect: conflict — Protected branch rule already exists
💡 Use gitlab_protected_branch_get to view current rules, or gitlab_protected_branch_update to modify

Error de validación

❌ create_issue: validation failed — title is too long (maximum is 255 characters)
💡 Shorten the title to 255 characters or less