Idempotencia, límites y errores de MiSender API

Idempotency-Key

Es obligatoria en cada POST /messages, admite hasta 190 caracteres y debe identificar una operación de negocio, no un intento HTTP.

Idempotency-Key: pedido-84721-confirmacion

• Misma clave y mismo cuerpo: devuelve el mensaje original con HTTP 200 e idempotent_replay: true.
• Misma clave y cuerpo diferente: HTTP 409 idempotency_conflict.
• La unicidad es por cuenta, incluso si rotas la API key.

Límites iniciales

• 120 solicitudes HTTP por minuto por llave.
• 30 mensajes por minuto por cuenta.
• Ráfaga de 10 mensajes cada 10 segundos.
• 20 templates por minuto.
• 1,000 mensajes aceptados al día.
• Máximo 200 mensajes pendientes.
• Cuerpo HTTP máximo de 256 KB.

Encabezados de control

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1790964060
Retry-After: 12

Formato de error

{
  "error": {
    "code": "outside_customer_window",
    "message": "Fuera de una ventana válida sólo se puede iniciar con una template aprobada.",
    "request_id": "req_..."
  }
}

Códigos HTTP

• 400: JSON o Idempotency-Key ausente.
• 401: API key ausente, inválida o revocada.
• 403: scope insuficiente, cuenta o API no disponible.
• 404: recurso inexistente para la cuenta.
• 409: conflicto de idempotencia.
• 413: payload mayor a 256 KB.
• 422: datos válidos como JSON, pero incompatibles con las reglas.
• 429: rate limit, cuota o cola alcanzada.
• 500: error interno inesperado.

Estrategia de reintento

Reintenta 429 respetando Retry-After y usa backoff exponencial con jitter. Para 500, conserva la misma Idempotency-Key: nunca fabriques una nueva para la misma operación. No reintentes automáticamente errores 4xx salvo 429.

Diagnóstico

Conserva siempre X-Request-Id o error.request_id, el código HTTP, fecha UTC y data.id. Nunca envíes la API key al soporte.