Errores de negocio

Para desarrolladores

Un 402 indica que el plan no permite la operación y explica cómo resolverlo. Aparece en dos casos:

• Límite del plan: la operación supera un cupo o una cuota del plan, o usa una funcionalidad que el plan no incluye.
• Suscripción inactiva: la suscripción de la cuenta no está activa.

A diferencia de un 401 o un 403, un 402 explica el motivo: el detail es descriptivo y la respuesta puede traer campos adicionales (limit, remaining, upgrade_url, ...), para que la integración pueda informar al usuario cómo resolverlo.

plan-send-limit-exceeded

code: plan_send_limit_exceeded · HTTP 402. El envío superaría la cuota de envíos del plan en el período vigente. La respuesta incluye limit (la cuota), remaining (lo que queda) y reset_at (cuándo se renueva la cuota). Con esos datos, la integración puede ofrecer al usuario esperar la renovación o actualizar el plan.

{
  "type": "https://docs.fidelizador.com/errors/plan-send-limit-exceeded",
  "title": "Payment Required",
  "status": 402,
  "detail": "Ha alcanzado el límite de envíos de su plan para este período. Puede esperar a la renovación de su ciclo o actualizar su plan.",
  "code": "plan_send_limit_exceeded",
  "trace_id": "...",
  "limit": 25000,
  "remaining": 0,
  "reset_at": "2026-06-28T00:00:00+00:00"
}

plan-webhooks-limit-exceeded

code: plan_webhooks_limit_exceeded · HTTP 402. Lo devuelve POST /v1/webhooks cuando el webhook nuevo superaría el cupo de webhooks del plan. Para el cupo cuentan todos los webhooks de la instancia, activos o pausados. Si el plan no incluye webhooks, el cupo es 0 y se devuelve este mismo código. La respuesta incluye limit (el cupo), usage (el uso actual), remaining (lo que queda) y upgrade_url (si está configurada).

{
  "type": "https://docs.fidelizador.com/errors/plan-webhooks-limit-exceeded",
  "title": "Payment Required",
  "status": 402,
  "detail": "Your plan's webhook limit has been reached. Upgrade your plan to add more webhooks.",
  "code": "plan_webhooks_limit_exceeded",
  "trace_id": "...",
  "limit": 0,
  "usage": 0,
  "remaining": 0
}

subscription-inactive

code: subscription_inactive · HTTP 402. La cuenta no tiene una suscripción activa o su plan no se pudo validar. También se devuelve al enviar si el plan no incluye envíos.

Si el plan no incluye una funcionalidad con cupo, como los webhooks, la respuesta no es este código sino el de esa funcionalidad, con limit: 0 (por ejemplo, plan_webhooks_limit_exceeded). Los envíos son la excepción: si el plan no los incluye, se devuelve subscription_inactive.