Engineering guide
Taxonomia de errores API para pipelines de archivos
Define clases de error estables y accionables para APIs de carga y procesamiento.
Codigo
Seguridad
Documento
Imagen
Video
Audio
Archivo
Por que importa una taxonomia de errores
Sin una taxonomia estable, clientes y soporte no pueden distinguir errores de usuario de defectos de plataforma. Un modelo de error tipado mejora la logica de retry, la calidad de la telemetria y la triage de incidentes.
Clases recomendadas
- input_invalid: entrada del usuario malformada o contraria a la politica.
- type_mismatch: desacuerdo entre extension, firma y parser.
- processing_failed: fallo de decode, transcode o extraccion.
- resource_limited: cuota, timeout o presupuesto de concurrencia excedido.
- internal_error: fallo inesperado del servicio.
Reglas operativas
Cada clase debe mapear a status codes deterministas, politicas de retry y patrones de mensajes para usuario. Instrumenta metricas por clase y codigo de motivo para que las regresiones sean medibles.
Herramientas recomendadas