Límites de plan y cómo evitar el 403

Todo lo que la API te deja hacer está acotado por la capacidad de tu plan, y esa capacidad es consultable: no tienes que adivinarla ni descubrirla cuando ya te topaste con un error. El endpoint de capacidades te dice, en cualquier momento, qué te permite tu plan y cuánto llevas usado.

Capacidades globales contra capacidades por entidad

Algunas capacidades se miden sobre el total de tu cuenta —memorias, agentes, powers— y su uso reportado refleja cuánto llevas acumulado. Otras se miden por entidad individual —mensajes por chat, imágenes por chat, parámetros por power, powers vinculados por agente— y ahí el uso llega vacío en la respuesta, porque no existe un total global que tenga sentido reportar: el límite se evalúa cada vez, sobre ese chat, ese power, ese agente puntual.

Free y Pro, lo que cambia

• Mensajes por chat: 20 en Free, 150 en Pro.
• Imágenes por chat: 1 en Free, 10 en Pro.
• Imágenes por día: 5 en Free, sin límite en Pro.
• Memorias, powers, parámetros por power, agentes y powers por agente comparten el mismo tope en ambos planes.

Sin límite se reporta de forma explícita

Cuando una capacidad no tiene techo en tu plan actual, la API lo reporta con un valor reservado para «sin límite», no con un campo vacío o ausente. No lo confundas con un error: es la forma en que la API distingue «no hay restricción» de «no pude calcular el límite».

Dos códigos, un mismo síntoma

Exceder una capacidad responde con un error 403, pero con un código distinto según qué límite tocaste: uno para lo que se mide como cuota de uso, otro para lo que se mide como tope de recurso. Ramifica por ese código si tu integración necesita reaccionar distinto —por ejemplo, sugiriendo actualizar de plan solo cuando el límite es de los que Pro efectivamente amplía.

Consulta antes de que tu usuario lo note

Si tu producto depende de una capacidad que puede agotarse —mensajes en un chat activo, por ejemplo—, consultar el endpoint de capacidades con cierta frecuencia y mostrar el margen restante evita que el límite se sienta como un muro repentino. Un aviso a tiempo es siempre mejor que un 403 en medio de una conversación importante.