Saltar al contenido principal

Errores de negocio

Para desarrolladores

Un 402 indica que el plan no permite la operación. 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, más un margen de tolerancia; en un plan que permite exceder la cuota, cuando superaría el tope de ese exceso. Hasta ahí el envío se acepta sin aviso en la respuesta (ver Límite de envíos del plan). 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
}

code: plan_consent_management_unavailable · HTTP 402. Lo dispara toda escritura del módulo de consentimientos cuando el plan no incluye la gestión de consentimientos: crear o modificar finalidades y términos, agregar un ítem de consentimiento a un formulario, activar un formulario que pide consentimiento, reenviar una confirmación, definir la exigencia de consentimiento de un remitente y registrar un consentimiento con POST /v1/consent-events. Las lecturas no se bloquean: los registros de consentimiento se pueden consultar siempre. La respuesta incluye upgrade_url (si está configurada).

{
  "type": "https://docs.fidelizador.com/errors/plan-consent-management-unavailable",
  "title": "Payment Required",
  "status": 402,
  "detail": "Consent management is not included in your plan. Upgrade your plan to manage consent.",
  "code": "plan_consent_management_unavailable",
  "trace_id": "...",
  "upgrade_url": "https://..."
}

plan-mcp-unavailable​

code: plan_mcp_unavailable · HTTP 402. Lo recibe el servidor MCP en cualquier llamada sobre una instancia cuyo plan no incluye el acceso por MCP. Se evalúa por instancia en cada llamada, y solo después de autorizar al usuario sobre esa instancia. El agente lo recibe traducido a un mensaje que indica revisar list_instances, donde cada instancia trae mcp_enabled. La respuesta incluye upgrade_url (si está configurada).

{
  "type": "https://docs.fidelizador.com/errors/plan-mcp-unavailable",
  "title": "Payment Required",
  "status": 402,
  "detail": "The MCP server for AI agents is not included in your plan. Upgrade your plan to connect an AI agent to this instance.",
  "code": "plan_mcp_unavailable",
  "trace_id": "...",
  "upgrade_url": "https://..."
}

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.

En esta página