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
Inspector MIME
Compara extension y firmas para detectar incompatibilidades de tipo.
Abrir herramientaClasificador MIME por lotes
Clasifica muchos archivos a la vez y resalta riesgos de incompatibilidad.
Abrir herramientaGenerador y verificador de checksum
Calcula SHA256 y verifica la integridad del archivo frente a hashes esperados.
Abrir herramienta