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.
403	module_disabled	La tool existe, pero tu organización tiene apagado el módulo que la contiene. La respuesta suma why, fix y module (el flag que falta).	Pedí que habiliten ese módulo. Si operás una agencia, mandá el header X-Pymaia-Org con una organización que lo tenga.
404	not_found	La tool no existe, o es solo-interna, o está excluida para conectores OAuth.	Verificá el nombre en la Referencia.
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 organización no tiene un módulo, sus tools se listan igual en /api/v1/tools —con module_disabled: true y el module que falta— y al llamarlas devuelven 403 module_disabled. El conector MCP las trata igual. Hasta el 15/09/2026 daban 404 y no se listaban: un «no existe» mandaba a revisar el nombre de la tool cuando lo que faltaba era habilitar el módulo.

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.