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
Sección titulada «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 | No existe, es inaccesible o supera tu tier de GitLab |
| 405 | No permitido | La acción no se aplica al estado actual del recurso |
| 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 | Gateway incorrecto | 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
Sección titulada «Funciones de envoltura de errores»El servidor usa cinco funciones de manejo 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 expiredUsada 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: 400El 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
Sección titulada «Á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 |
NotFoundResult — Respuestas informativas para 404
Sección titulada «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_branch_list` to see available branches- Check branch name spelling and case sensitivityEste patrón se aplica mediante un formateador compartido en cada uno de 19 dominios, de modo que todos los handlers get de un dominio responden igual. Se registra a nivel INFO (resultado esperado) y proporciona al asistente de IA los siguientes pasos accionables.
Sugerencias correctivas
Sección titulada «Sugerencias correctivas»Cuando se conoce la corrección de un error, el handler la adjunta en el punto de llamada: WrapErrWithStatusHint añade la sugerencia solo cuando la respuesta lleva un estado HTTP concreto (un fallo de validación 422, un 404, un 409) y recurre a WrapErrWithMessage para cualquier otro estado, mientras que WrapErrWithHint la añade siempre, que es lo que necesitan los errores de GraphQL, ya que no llevan código de estado. La sugerencia viaja en el texto del error como Suggestion: ..., de modo que el asistente de IA puede corregir su solicitud sin llamadas adicionales a la API.
Formato de respuesta de error
Sección titulada «Formato de respuesta de error»Cuando un handler responde con un resultado de error en lugar de un error de Go, la respuesta es un bloque Markdown con campos de diagnóstico estructurados:
## ❌ Error: branch/list
**Message**: authentication failed: GITLAB_TOKEN may be invalid or expired**HTTP Status**: 401 (authentication failed: GITLAB_TOKEN may be invalid or expired)**Details**: GET https://gitlab.example.com/api/v4/projects/42/repository/branches: 401 (401 Unauthorized)**Request ID**: `abc123def456`La respuesta estructurada incluye:
| Campo | Descripción |
|---|---|
| Encabezado | El dominio y la acción que fallaron |
| Message | El mensaje de error clasificado |
| HTTP Status | El código de estado de GitLab y su clasificación, cuando lo hubo |
| Details | La línea de la petición y el mensaje que devolvió GitLab, si lo hay |
| Request ID | El X-Request-Id de GitLab para tickets de soporte |
Errores transitorios vs permanentes
Sección titulada «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
Sección titulada «Ejemplos de escenarios de error»Token inválido
Sección titulada «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 TokensPermiso denegado
Sección titulada «Permiso denegado»❌ create_issue: access denied — your token lacks the required permissionsDetail: 403 Forbidden💡 Ensure the token has api scope and you have Developer+ access to the projectConflicto de recurso
Sección titulada «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 modifyError de validación
Sección titulada «Error de validación»❌ create_issue: validation failed — title is too long (maximum is 255 characters)💡 Shorten the title to 255 characters or lessPreguntas frecuentes
¿Cómo clasifica el servidor los errores de la API de GitLab?
GitLab MCP Server clasifica cada error de API por código de estado HTTP en un mensaje accionable: 401 señala un GITLAB_TOKEN inválido o expirado, 403 señala permisos faltantes, 404 un recurso inexistente o falta de acceso, 422 un fallo de validación y 429 un límite de velocidad. Los fallos a nivel de red —conexión rechazada, fallo DNS, timeout y errores de handshake TLS— se clasifican por separado. La clasificación determina tanto el mensaje de error envuelto como si el fallo se considera reintentable.
¿Qué función de envoltura de errores se usa para cada operación?
Las operaciones de solo lectura (list, get, search) usan WrapErr. Las operaciones de escritura (create, update, delete) usan WrapErrWithMessage, que incluye el detalle específico extraído de la respuesta de GitLab. Cuando se conoce la acción correctiva, WrapErrWithHint añade una sugerencia, y WrapErrWithStatusHint limita esa sugerencia a un único código de estado HTTP. Una operación get que devuelve 404 usa NotFoundResult en lugar de devolver un error.
¿Por qué un 404 no aparece como error?
Para los handlers get, las respuestas 404 se tratan como informativas 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, registrado a nivel INFO. Este patrón NotFoundResult se aplica mediante un formateador compartido en cada uno de 19 dominios y proporciona al asistente de IA los siguientes pasos accionables, como listar los recursos disponibles o verificar el nombre del recurso.
¿Debería el asistente de IA reintentar una operación fallida?
Depende de si el error es transitorio o permanente. Los errores transitorios —429, 5xx, timeouts y conexión rechazada— son seguros de reintentar tras una espera. Los errores permanentes —4xx excepto 429— indican un problema con la propia solicitud, así que reintentar produce el mismo resultado. Para errores permanentes, corrige los parámetros de entrada o la configuración en lugar de reintentar.