Errores y reintentos

Cada respuesta de Mono lleva un código de estado HTTP. Las llamadas exitosas devuelven 2xx; las fallas devuelven 4xx (tu solicitud estaba mal) o 5xx (algo salió mal del lado de Mono). Esta página documenta los códigos de estado que usa Mono, el envelope de error que puedes esperar en cada falla, y la política de reintentos que convierte fallas transitorias en éxito eventual sin duplicar efectos secundarios.

Códigos de estado HTTP

Envelope de error

Cada respuesta de falla lleva un envelope JSON estándar para que los clientes puedan parsear errores de forma uniforme:

{
  "code": "400 Bad Request",
  "errors": [
    {
      "error_code": "item_not_found",
      "message": "Item doesn't exist",
      "path": "#/item/id",
      "url": "https://api.mono.co/docs#errors"
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Malformed request"
}

Campos:

• code — el estado HTTP y su frase de razón (por ejemplo, "404 Not Found").
• errors[] — una entrada por cada falla de validación. Útil cuando una sola solicitud tiene varios campos inválidos.
  • error_code — código estable y legible por máquina para esta falla específica.
  • message — descripción humana corta.
  • path — puntero JSON al payload de la solicitud que identifica el campo ofensor.
  • url — link a documentación extendida para este código de error, cuando esté disponible.
• id — identificador de solicitud generado por Mono. Inclúyelo cuando contactes a soporte — nos permite localizar la solicitud exacta en nuestros logs.
• message — descripción humana de alto nivel apta para mostrar a operadores (no a usuarios finales).

Las respuestas de 429 y otros límites de tasa usan el mismo envelope con error_code: "rate_limited".

Cuándo reintentar

Reintenta solo en fallas transitorias, nunca en errores de aplicación:

Cuatro reglas aplican a cada reintento:

1. Respeta Retry-After. Si el header está presente (siempre en 429, a veces en 503), espera al menos esos segundos antes de reintentar. No reintentes antes.
2. Usa backoff exponencial con jitter cuando Retry-After esté ausente. Empieza en 1 segundo, dobla en cada falla subsecuente, agrega 0–500 ms de jitter aleatorio, y limita el delay a 30 segundos. El jitter previene el problema de thundering herd donde muchos clientes reintentan en sincronía.
3. Limita el presupuesto de reintentos. Hasta 5 reintentos por operación lógica es un valor por defecto razonable. Después de eso, surface la falla — reintentar para siempre solo desplaza el problema.
4. Reusa la clave de idempotencia. Cada reintento debe llevar la misma X-Idempotency-Key que el intento original. De lo contrario, un reintento exitoso tras un 5xx ambiguo podría cobrarle dos veces a un cliente.

Un bucle de reintento mínimo en Python:

import random
import time

import httpx

RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}

def request_with_backoff(client, method, url, **kwargs, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries + 1):
        response = client.request(method, url, **kwargs)
        if response.status_code not in RETRYABLE_STATUSES:
            return response

        retry_after = response.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else delay + random.uniform(0, 0.5)
        time.sleep(min(wait, 30.0))
        delay = min(delay * 2, 30.0)

    return response  # last response, still failing

Diseñar para resiliencia desde el inicio

Incluso antes de que los límites de tasa se vuelvan estrictos, tres hábitos mantienen las cargas en ráfaga fuera de problemas:

• Distribuye el trabajo en ráfaga. Trabajos por lotes que disparan miles de llamadas — corridas de nómina, conciliación de fin de día, emisión masiva de tarjetas — deberían ser ritmados del lado del cliente en lugar de dispararse en paralelo. Unas pocas solicitudes por segundo sostenidas le ganan a mil al tiempo seguidas de una ventana de recuperación.
• Cachea lecturas. Los datos de referencia (catálogos, esquemas de tarifas, lookups de capacidades) rara vez cambian dentro de un solo ciclo de solicitud. Cachea la respuesta y solo pega a Mono cuando falla el cache.
• Separa rutas síncronas de las asíncronas. Una llamada de checkout cara a un usuario no debería compartir su presupuesto con una exportación nocturna. Usa API keys distintas para cargas distintas cuando sea posible, para que un trabajo por lotes desbocado no agote el límite que necesita un cliente real.

Errores comunes

Siguientes pasos

• Claves de idempotencia — requeridas en cada escritura reintentada.
• Autenticación — manejo de credenciales para los casos 401 y 403.
• Webhooks — la política de reintentos de Mono para los eventos que envía a tu sistema.