Saltar al contenido principal

Errores de negocio

Códigos específicos de dominio (definidos en billing-entitlement, emitidos por saascore-api e instance-api). A diferencia de 401/403, el 402 lleva cuerpo descriptivo (title/detail propios + miembros extra + upgrade_url) porque un límite de plan es una superficie de conversión, no un secreto de seguridad.

plan-user-limit-exceeded​

code: plan_user_limit_exceeded · HTTP 402 · saascore-api. Lo dispara PUT /v1/instances/{slug}/users/{username} (asignar un asiento) cuando hacerlo superaría el cupo de asientos del plan de la instancia. Miembro extra limit (el cupo) y upgrade_url (si está configurada). El cupo se mide en asientos — ver conteo del cupo.

{
  "type": "https://docs.fidelizador.com/errors/plan-user-limit-exceeded",
  "title": "Límite de usuarios del plan alcanzado",
  "status": 402,
  "detail": "Ha alcanzado el número máximo de usuarios incluido en su plan. Para agregar más usuarios, debe actualizar su plan.",
  "code": "plan_user_limit_exceeded",
  "trace_id": "...",
  "limit": 5,
  "upgrade_url": "https://..."
}

plan-send-limit-exceeded​

code: plan_send_limit_exceeded · HTTP 402 · instance-api. El envío superaría la cuota de envíos del plan para el ciclo de envío actual (la ventana de reset del medidor). Miembros extra limit (la cuota), remaining (lo que queda) y reset_at (cuándo se renueva el ciclo), para que el cliente pueda ofrecer "esperar a 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-custom-domains-limit-exceeded​

code: plan_custom_domains_limit_exceeded · HTTP 402 · instance-api. Lo dispara POST /v1/private/domains cuando crear un dominio superaría el cupo de dominios personalizados del plan. El alta de dominios no existe en la superficie pública. El cupo se mide sobre los dominios activos de la instancia (no eliminados). Miembros extra limit (el cupo), usage, remaining y upgrade_url (si está configurada).

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

plan-senders-limit-exceeded​

code: plan_senders_limit_exceeded · HTTP 402 · instance-api. Lo dispara POST /v1/private/senders cuando crear un remitente superaría el cupo de remitentes del plan. El alta de remitentes no existe en la superficie pública. El cupo se mide sobre los remitentes activos de la instancia (no eliminados) y aplica también a la reactivación de un remitente eliminado. Miembros extra limit (el cupo), usage, remaining y upgrade_url (si está configurada).

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

plan-api-access-control-unavailable​

code: plan_api_access_control_unavailable · HTTP 402 · instance-api. Lo disparan POST /v1/private/api-keys y PATCH /v1/private/api-keys/{id} al crear o editar una key con access_type: scoped (permisos finos por key) cuando el plan no incluye el control de acceso de API (entitlement boolean relay.security.api-access-control). Las keys con access_type: all (acceso total) no se ven afectadas, y las keys scoped ya existentes se siguen respetando. Miembro extra upgrade_url (si está configurada).

{
  "type": "https://docs.fidelizador.com/errors/plan-api-access-control-unavailable",
  "title": "Payment Required",
  "status": 402,
  "detail": "Fine-grained API key scopes are not included in your plan. Upgrade your plan to create scoped API keys.",
  "code": "plan_api_access_control_unavailable",
  "trace_id": "...",
  "upgrade_url": "https://..."
}

subscription-inactive​

code: subscription_inactive · HTTP 402 · saascore-api e instance-api. Default fail-closed: la instancia no tiene una suscripción usable, el snapshot de entitlements es malformado/no resoluble, o el plan no incluye el entitlement del gate (gestión de usuarios en saascore-api, envío en instance-api). Nota: para el gate boolean de control de acceso de API, "el plan no incluye el entitlement" se devuelve como plan_api_access_control_unavailable (no subscription_inactive), porque billing omite la key cuando el plan no la incluye; subscription_inactive queda para los casos de sin-suscripción o snapshot inválido.

En esta página