Errores y límites

Cuando una llamada falla, la respuesta es siempre JSON con esta forma y el status HTTP correspondiente:

{ "ok": false, "error": "<mensaje>", "outcome": "<motivo>", "duration_ms": 12 }

Códigos

HTTP	outcome	Qué pasó	Cómo resolver
401	—	Falta el Authorization: Bearer o la clave es inválida/expirada.	Revisá el header y que la key no esté revocada. Regenerala en Ajustes → API Keys.
403	denied_scope	La key no tiene el scope que el endpoint requiere.	Agregá el scope a la key (ver Scopes) o usá una key con más permisos.
404	not_found	La tool no existe, o tu plan tiene apagado el módulo que la contiene, o es una tool solo-interna.	Verificá el nombre en la Referencia. Si es un módulo (ej. MercadoLibre), activalo en tu plan.
429	rate_limited	Superaste el límite de llamadas por minuto de esa tool.	Esperá y reintentá con backoff. El límite por defecto es 60/min; algunas tools tienen menos.
402	cost_cap	La org llegó a su tope de gasto (créditos IA / operaciones pagas).	Revisá tu saldo de créditos; subí el tope o esperá al reset mensual.
400	error	Parámetros inválidos (no matchean el esquema) o el handler falló.	Revisá los parámetros contra la Referencia. El error trae el detalle.

Rate limits

Cada tool tiene un límite de llamadas por minuto por organización. El default es 60/min; consultá el valor exacto de cada una en GET /api/v1/tools (campo rate_limit_per_minute). Ante un 429, reintentá con backoff exponencial.

Aislamiento y módulos

• Toda llamada está scopeada a tu organización: una key nunca ve datos de otra (salvo el override de agencia X-Pymaia-Org, limitado a orgs accesibles del usuario dueño de la key).
• Si tu plan no incluye un módulo, sus endpoints devuelven 404 — no se listan en /api/v1/tools. Es el mismo criterio que oculta el módulo en la UI.

Acciones que modifican plataformas

Las tools que escriben en tus plataformas (pausar campañas, cambiar presupuestos, responder MercadoLibre) pasan por el Trust Layer: proponen la acción y requieren aprobación (actions:approve). No se ejecutan directo desde una llamada, por diseño.