ID del artículo: TECH-HTTP-001
Última actualización: enero de 2025
Categoría: Soporte técnico / Integración
Etiquetas: Exportación HTTP, Solución de problemas, Tiempo de espera de la puerta de enlace, Errores de integración

📋 Resumen del artículo

Esta guía ayuda a los clientes a diagnosticar y resolver problemas relacionados con la recepción de exportaciones automatizadas de mediciones de energía mediante HTTP. Abarca errores comunes, sus soluciones y ofrece un enfoque sistemático para la resolución de problemas.

🎯 Se aplica a

• Clientes que utilizan la funcionalidad de exportación HTTP/HTTPS
• Administradores de sistemas que gestionan puntos finales HTTP
• Equipos de soporte técnico

⚡ Buscador rápido de soluciones

📝 Requisitos previos

Antes de solucionar problemas, verifique que su servidor HTTP cumpla con estos requisitos:

✅ Acepta un tamaño de carga útil mínimo de 1 MB
✅ Devuelve el estado HTTP 200 OK en caso de recepción exitosa
✅ Admite métodos POST, PUT o POST MULTIPART
✅ Puede gestionar múltiples transacciones para grandes exportaciones (>2000 mediciones)

🔧 Tipos de errores comunes y soluciones

1. Errores de tiempo de espera de la puerta de enlace

Detalles del error:

• Mensaje: Gateway Timeout
• Tipo: CLIENT_ERROR
• Estado HTTP: 504

Causas fundamentales:

• El procesamiento del servidor supera el tiempo de espera de 60 segundos
• El tiempo de espera del proxy/balanceador de carga es demasiado restrictivo
• Cuellos de botella en el rendimiento del backend

Solución paso a paso:

Aumentar la configuración del tiempo de espera

Para Nginx:

# Add to your server or location block
proxy_read_timeout 300s;
proxy_connect_timeout 75s;
proxy_send_timeout 300s;

Para Apache:

# Add to httpd.conf or .htaccess
Timeout 300
ProxyTimeout 300

Para IIS:

<system.webServer>
  <httpProtocol>
    <customHeaders>
      <add name="Keep-Alive" value="timeout=300" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

Optimizar el rendimiento del procesamiento

• Monitorizar la CPU/memoria durante las exportaciones
• Implementar el procesamiento asincrónico
• Considere devolver 200 inmediatamente y procesarlo en segundo plano

2. Errores de tiempo de espera de lectura

Detalles del error:

• Mensaje: Read timed out
• Tipo: INTERNAL_ERROR
• Frecuencia: Muy común (códigos de estado 261-262)

Causas fundamentales:

• Interrupción de la conectividad de la red
• Firewall que bloquea conexiones sostenidas
• Problemas de protocolo de enlace SSL/TLS

Solución paso a paso:

Diagnóstico de red

# Test connectivity
telnet your-server.com 443

# Check SSL certificate
openssl s_client -connect your-server.com:443

Configuración del firewall

• Incluir en la lista blanca nuestras IP de servicio de exportación (contactar con el soporte técnico para obtener la lista)
• Asegúrese de que se permitan conexiones persistentes
• Consultar las reglas de limitación de velocidad

Comprobación del estado del servidor

# Monitor connections during export window
netstat -an | grep :443 | grep ESTABLISHED

3. Errores de resolución de DNS

Detalles del error:

• Mensaje: Name or service not known
• Tipo: CLIENT_ERROR
• Ejemplo: ops.autodeskbuildingops.com: Name or service not known

Causas fundamentales:

• Nombre de host/URL incorrecto
• Problemas de configuración de DNS
• Caducidad o cambios de dominio

Solución paso a paso:

Verificar la configuración del dominio

# Check DNS resolution
nslookup your-domain.com
dig your-domain.com

# Verify from our perspective
curl -I https://your-domain.com/your-endpoint

Soluciones comunes

• Asegúrese de que el dominio se pueda resolver públicamente
• Comprobar errores tipográficos en la URL configurada
• Verificar que el certificado SSL coincida con el dominio

4. Errores internos del servidor

Detalles del error:

• Mensaje: Internal Server Error
• Tipo: CLIENT_ERROR
• Estado HTTP: 500

Causas fundamentales:

• La aplicación se bloquea al procesar la carga útil
• Recursos del servidor insuficientes
• Errores de código o configuraciones incorrectas

Solución paso a paso:

Habilitar el registro de errores de la aplicación

Comprobar los límites de recursos

# Memory
free -m

# Disk space
df -h

# Process limits
ulimit -a

Prueba con carga útil de muestra (ver Pasos de depuración)

🔍 Pasos de depuración completos

Paso 1: Habilitar el registro detallado (CRÍTICO)

⚠️ Importante: El registro detallado es esencial para la resolución de problemas. Sin registros detallados, no podemos diagnosticar los problemas eficazmente.

Configuración de Nginx:

# /etc/nginx/nginx.conf
error_log /var/log/nginx/error.log debug;
access_log /var/log/nginx/access.log combined;

# Log request body for debugging
log_format postdata '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $bytes_sent '
                    '"$http_referer" "$http_user_agent" "$request_body"';

Configuración de Apache:

# Enable debug logging
LogLevel debug
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined

# Log POST data (use cautiously)
DumpIOInput On
DumpIOOutput On

Registro a nivel de aplicación (ejemplo de Node.js):

const fs = require('fs');
const logStream = fs.createWriteStream('./export-debug.log', { flags: 'a' });

app.use((req, res, next) => {
  const timestamp = new Date().toISOString();
  const logEntry = {
    timestamp,
    method: req.method,
    url: req.url,
    headers: req.headers,
    contentLength: req.headers['content-length'],
    ip: req.ip
  };
  
  logStream.write(JSON.stringify(logEntry) + '\n');
  
  // Log response
  const originalSend = res.send;
  res.send = function(data) {
    logStream.write(`Response: ${res.statusCode} at ${new Date().toISOString()}\n`);
    originalSend.call(res, data);
  };
  
  next();
});

Paso 2: Pruebe el punto final manualmente

Prueba básica:

curl -X POST https://your-server.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [{
      "device_id": 47653,
      "device_name": "Test Device",
      "measurement_time(UTC)": "2021-08-10T08:48:00Z",
      "resolution(minutes)": 1,
      "site_id": 3026,
      "site_name": "Test Site",
      "current(A)": 3.7,
      "voltage(V)": 230,
      "power(W)": 807.4,
      "power_factor": 0.95,
      "energy(Wh)": 13.5
    }]
  }' \
  -w "\n\nHTTP Code: %{http_code}\nTotal Time: %{time_total}s\nConnect Time: %{time_connect}s\nStart Transfer: %{time_starttransfer}s\n" \
  -v

Prueba de gran carga útil:

# Create large test file
echo '{"measurements":[' > large-test.json
for i in {1..2000}; do
  echo '{"device_id":'$i',"device_name":"Device'$i'","measurement_time(UTC)":"2021-08-10T08:48:00Z","resolution(minutes)":1,"site_id":3026,"site_name":"Test Site","current(A)":3.7,"voltage(V)":230,"power(W)":807.4,"power_factor":0.95,"energy(Wh)":13.5},' >> large-test.json
done
echo ']}' >> large-test.json

# Test with large payload
curl -X POST https://your-server.com/endpoint \
  -H "Content-Type: application/json" \
  -d @large-test.json \
  -w "\nPayload Size: %{size_upload} bytes\nTime: %{time_total}s\n"

Paso 3: Monitorizar durante la ventana de exportación

Identificar el cronograma de exportación

• Verifique su configuración de exportación para los horarios programados
• Tenga en cuenta las diferencias de zona horaria (las exportaciones utilizan UTC)

Script de monitoreo en tiempo real:

#!/bin/bash
# monitor-exports.sh

LOG_FILE="/var/log/nginx/access.log"
ERROR_FILE="/var/log/nginx/error.log"

echo "Monitoring exports... Press Ctrl+C to stop"
tail -f $LOG_FILE $ERROR_FILE | grep -E "POST|PUT|500|502|504"

Monitoreo de recursos:

# Run during export window
top -b -n 1 > resource-snapshot.txt
iostat -x 1 10 >> resource-snapshot.txt

✅ Lista de verificación de diagnóstico

Utilice esta lista de verificación para garantizar que se aborden todos los problemas comunes:

• [ ] Configuración del punto final
  • [ ] Acepta métodos POST/PUT/POST MULTIPART
  • [ ] Devuelve exactamente HTTP 200 OK (sin redirecciones)
  • [ ] Sin autenticación o configurado correctamente
• [ ] Capacidad y rendimiento
  • [ ] Puede manejar cargas útiles de más de 1 MB
  • [ ] Configuración de tiempo de espera >60 segundos en todas las capas
  • [ ] Suficiente CPU/memoria durante las horas pico
• [ ] Red y seguridad
  • [ ] El firewall permite conexiones entrantes
  • [ ] Certificados SSL/TLS válidos y no vencidos
  • [ ] El DNS se resuelve correctamente desde redes externas
• [ ] Registro y monitoreo
  • [ ] Registro detallado habilitado
  • [ ] Registros conservados durante al menos 7 días
  • [ ] Alertas de monitoreo configuradas

📊 Datos a recopilar para soporte

Al contactar con el soporte, proporcione:

1. Información de error

Export Configuration ID: [Your ID]
Error Message: [Exact error from logs]
Failure Timestamps: [UTC times]
Frequency: [How often it occurs]

2. Registros del servidor (OBLIGATORIO)

Incluya al menos 3 intentos fallidos que muestren:

• Encabezados de solicitud completos
• Códigos de respuesta
• Duración del procesamiento
• Cualquier seguimiento de pila de errores

3. Detalles de configuración

Web Server: [Type and Version]
OS: [Operating System]
Timeout Settings: [All relevant timeouts]
Proxy/LB: [If applicable]
SSL Certificate: [Expiry date]

4. Resultados de la prueba

• Salida de prueba de rizo manual
• Resultados de pruebas de gran carga útil
• Uso de recursos durante fallos

5. Información de la red

Public IP: [Your server IP]
Firewall Rules: [Relevant rules]
Rate Limits: [If configured]

💡 Mejores prácticas

Implementar un registro robusto

# Python example with rotation
import logging
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    'export-receiver.log',
    maxBytes=10485760,  # 10MB
    backupCount=10
)
logging.basicConfig(handlers=[handler], level=logging.DEBUG)

Patrón de respuesta rápida

// Return 200 immediately, process async
app.post('/export', (req, res) => {
  res.status(200).send('OK');
  
  // Process in background
  setImmediate(() => {
    processExportData(req.body);
  });
});

Punto final de comprobación de estado

@app.route('/health')
def health_check():
    return {'status': 'healthy', 'timestamp': datetime.utcnow()}, 200

Supervisar la disponibilidad de los puntos finales

• Utilice servicios de monitorización del tiempo de actividad
• Configurar alertas para fallos
• Seguimiento de tendencias de tiempos de respuesta

🆘 ¿Aún necesitas ayuda?

Si los problemas persisten después de seguir esta guía:

1. Recopilar toda la información de diagnóstico mencionada anteriormente
2. Habilitar el registro detallado y capturar múltiples intentos fallidos
3. Ejecute las pruebas manuales y guarde los resultados
4. Contacte con el soporte técnico con:
   • Este artículo referencia (TECH-HTTP-001)
   • Todos los datos de diagnóstico recopilados
   • Su ID de configuración de exportación

Recuerde: las exportaciones fallidas se vuelven a intentar automáticamente durante hasta 7 días, lo que garantiza que no haya pérdida de datos durante la resolución de problemas.

📚 Artículos relacionados

• [Guía de configuración de exportación HTTP]
• [Comprensión del formato de datos de exportación]
• [Mejores prácticas de seguridad para puntos finales HTTP]
• [Webhook vs Exportación HTTP: ¿Cuál elegir?]

Comentarios: ¿Te resultó útil este artículo? [Sí] [No] [Reportar un problema]