Contrato de errores de MCP
El transporte estándar de POM AI utiliza los siguientes errores de JSON-RPC 2.0 para los fallos de protocolo y de los métodos MCP.
| Código JSON-RPC | Significado |
|---|---|
-32700 |
El cuerpo del POST no es un JSON válido. |
-32600 |
El mensaje no es una solicitud JSON-RPC 2.0 válida. |
-32601 |
El método JSON-RPC solicitado no es compatible. |
-32029 |
Se superó una cuota o no se pudo completar la limitación de solicitudes. Inspecciona error.data.code y error.data.status; los errores de cuota también incluyen retry_after. |
-32000 |
Se produjo un error de dominio de POM AI al leer un recurso/prompt o al llamar a una herramienta. |
Los fallos de dominio incluyen un código público estable en error.data.code, por ejemplo pom_ai_mcp_unknown_tool, pom_ai_mcp_scope_denied, pom_ai_mcp_resource_not_found, o un error específico de la herramienta de capacidad, puerta, esquema, objeto o lista de permitidos.
La autenticación puede fallar en el límite HTTP/REST antes de que se ejecute un método JSON-RPC. Conserva tanto el estado HTTP como el código de error POM cuando estén disponibles.
Errores del adaptador nativo
En el modo WordPress MCP Adapter, un fallo de ejecución de herramienta o de permiso devuelve result.isError: true con un elemento de texto explicativo. Un HTTP 200 por sí solo no establece el éxito. El adaptador no conserva el error.data.code del transporte estándar para los fallos de ejecución de herramientas; no hagas ramificaciones basadas en texto traducido. Los fallos de protocolo, recursos y prompts utilizan las respuestas de error JSON-RPC del adaptador.
Los fallos de autenticación pueden, en su lugar, devolver un error HTTP antes del envío. El modo nativo devuelve 401 para credenciales faltantes/no válidas, 403 para acceso de transporte denegado, 429 cuando se agota su cuota de solicitudes y 503 cuando la limitación de solicitudes o la dependencia del adaptador seleccionada no está disponible. La finalización o caducidad de la sesión requiere la inicialización de una nueva sesión. El modo nativo rechaza los lotes JSON-RPC con HTTP 400.
Comportamiento del cliente
- Haz coincidencias con los códigos cuando se suministren, y comprueba
isErrorpara los resultados nativos de las herramientas; nunca hagas ramificaciones basadas en el texto traducido del mensaje. - Trata
-32029como una condición de reintentar más tarde. - Trata la denegación de ámbito, capacidad, puerta y lista de permitidos como trabajo de configuración o autorización, no como un fallo transitorio.
- En un tiempo de espera de escritura, lee el estado actual antes de reintentar.
- No expongas cuerpos de solicitud sin procesar ni credenciales en diagnósticos orientados al usuario.
Un tools/call exitoso tiene isError: false. Los fallos de dominio de herramienta no se devuelven como contenido de texto exitoso.
Guías relacionadas: transport, rate limiting y safe support information.