Skip to main content

Taxonomía de errores

La request no llegó al API, o la respuesta fue rechazada antes de procesarse.
  • HTTP 404: URL mal escrita.
  • HTTP 415: Content-Type incorrecto.
  • HTTP 500/502/503: problema del servidor.
  • Timeout: red o servidor saturado.
Acción: reintentar con backoff. No son errores del negocio.

Patrón recomendado

Retry con backoff (solo para errores de red)

Nunca reintentes int_codigo: 2. Si las credenciales son malas o un campo está mal, reintentar no lo va a arreglar — solo multiplica el error.

Mensajes de error conocidos

Los mensajes de error del API no son consistentes ni siempre descriptivos. Loguea siempre el response completo para poder diagnosticar. [Pendiente con TI: estandarizar mensajes de error.]

Qué mostrar al usuario

Nunca muestres str_descripcion_error crudo al usuario.
Puede contener nombres de variables internas o información sensible.
Mapea errores técnicos a mensajes de negocio:

Alertas operativas

Configura alertas para:
  • Tasa de errores de red > 1% en los últimos 10 min → problema del lado de Zonapagos o de tu red.
  • Tasa de int_codigo: 2 > 5% → probablemente bug en tu código (credenciales mal, campo mal construido).
  • Sonda no ejecutada en > 30 min → tu cron murió. Los pagos pendientes se acumulan.
  • Pagos en estado 999 > 24h → requieren intervención manual.

Ver también

Errores comunes

Tabla completa de errores con diagnóstico.

Logging

Qué loguear para facilitar debugging.