Manejo de Errores

REST API — Todos los endpoints requieren autenticación mediante Bearer token. Incluye Authorization: Bearer {token} en cada solicitud. Los tokens se gestionan en Configuración de GitScrum → API. Base URL: https://services.gitscrum.com — Todas las rutas de solicitud en esta documentación son relativas a esta URL base.

La API de GitScrum utiliza códigos de estado HTTP estándar y devuelve respuestas de error JSON estructuradas.

Códigos de estado HTTP

Formato de respuesta de error

Todas las respuestas de error siguen una estructura consistente:

{
  "error": "Not Found",
  "message": "The requested resource was not found."
}

Errores de validación (422)

Los errores de validación incluyen detalles a nivel de campo:

{
  "error": "Validation Error",
  "message": "The given data was invalid.",
  "errors": {
    "title": ["The title field is required."],
    "company_slug": ["The selected company slug is invalid."]
  }
}

Cada clave en el objeto errors corresponde a un campo de la solicitud, y el valor es un array de mensajes de validación.

Errores de autenticación (401)

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Verifica que tu token sea válido y esté incluido en el header Authorization. Consulta Autenticación.

Errores de permisos (403)

{
  "error": "Forbidden",
  "message": "You do not have permission to perform this action."
}

Verifica que tu cuenta tenga el rol requerido para el workspace o proyecto.

Mejores prácticas

• Verifica códigos de estado — Siempre inspecciona el código de estado HTTP antes de analizar el cuerpo de la respuesta.
• Maneja reintentos — Reintenta errores 429 y 5xx con backoff exponencial. No reintentes errores 4xx del cliente.
• Registra errores — Captura la respuesta de error completa (estado, mensaje, objeto errors) para depuración.
• Valida localmente — Valida los campos requeridos antes de enviar solicitudes para evitar respuestas 422 innecesarias.
• Muestra mensajes — Usa el campo message para mostrar retroalimentación de error amigable al usuario.