Errors i límits de peticions

El servidor MCP parla JSON-RPC 2.0 estricte. Els errors tornen com un objecte error, mai com un cos d'error HTTP a l'estil de l'API REST — però la semàntica és idèntica: la mateixa violació de regla de negoci que retorna 422 sobre REST retorna aquí l'error equivalent —un error JSON-RPC, o un resultat isError quan es produeix dins d'una tool— amb el code i l'http_status de v1 conservats.

Aquesta pàgina cobreix el mapatge JSON-RPC específic d'MCP i els buckets de throttling d'MCP. Per al contracte REST canònic — l'embolcall d'error per code i les quotes per tier — consulta Errors i Límits de peticions.

Errors mentre s'executa una tool

Un error de domini que es produeix mentre una tool s'executa —una regla de negoci (422), un recurs inexistent (404), un conflicte (409)— no torna com un error JSON-RPC. El protocol reserva aquest per als errors de protocol, així que la tool respon amb un resultat normal marcat isError: true, que el model pot llegir i corregir:

{
  "jsonrpc": "2.0",
  "id": "<request id>",
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "La factura ya emitida no puede modificarse." }],
    "_meta": {
      "com.factuarea/error": {
        "http_status": 422,
        "code": "invoice_cannot_be_modified",
        "hint": "La factura ya emitida no puede modificarse.",
        "param": "status"
      }
    }
  }
}

• content[0].text és el missatge del domini (el mateix hint que retorna la REST API), també en producció.
• _meta["com.factuarea/error"] porta el contracte de l'error REST: http_status, code, hint i, quan s'apliquen, param, subcode i details (per exemple existing_resource_id d'un duplicat). Ramifica per code, com fas per REST.
• Només un 5xx es reporta com una fallada nostra; un rebuig és ús normal.

Les guardes que corren abans de la tool —autenticació, scopes i pla, límits de peticions, guardrails fiscals, idempotència i els noms de tool retirats— continuen responent amb un error JSON-RPC, com descriu la resta d'aquesta pàgina.

Forma de l'error

{
  "jsonrpc": "2.0",
  "id": "<request id>",
  "error": {
    "code": -32008,
    "message": "invoice_cannot_be_modified",
    "data": {
      "http_status": 422,
      "code": "invoice_cannot_be_modified",
      "hint": "La factura ya emitida no puede modificarse.",
      "param": "status"
    }
  }
}

• error.code — el codi numèric JSON-RPC (les correspondències de negoci fan servir -32099..-32000; els errors de protocol inclouen -32602 i els interns fan servir -32603).
• error.message — un identificador de cadena estable (p. ex. insufficient_scope, invoice_cannot_be_modified).
• error.data.code — el mateix code canònic de v1 que retorna l'API REST, de manera que puguis ramificar segons un únic valor a totes dues superfícies.
• error.data.http_status — l'estat HTTP que retornaria la crida REST equivalent (422 / 404 / 409 / …), per a clients que prefereixen raonar en termes HTTP.
• error.data.hint — un missatge llegible per a persones (en castellà, d'acord amb l'idioma de l'app). Altres camps (param, subcode, required_scope, …) apareixen quan són rellevants.

Taula de codis

Scope insuficient

Quan una tool necessita un scope que la credencial no té:

{
  "jsonrpc": "2.0",
  "id": "req-42",
  "error": {
    "code": -32005,
    "message": "insufficient_scope",
    "data": {
      "http_status": 403,
      "code": "insufficient_scope",
      "required_scope": "invoices:write",
      "provided_scopes": ["invoices:read", "contacts:read"],
      "hint": "La credencial no tiene el scope requerido para esta operación."
    }
  }
}

Les tools que la teva credencial no pot assolir també queden ocultes a tools/list, de manera que un agent ben comportat normalment no les intentarà — aquest error és la xarxa de seguretat.

Límits de peticions

Les peticions es limiten en tres buckets independents. Superar-ne qualsevol retorna -32006 amb una capçalera Retry-After (segons).

Per token, per categoria de tool

Cada credencial té comptadors per minut separats per categoria de tool, de manera que un ús destructiu intensiu no pugui esgotar les teves lectures:

El bucket es resol a partir de la categoria de la tool. El comptador s'incrementa abans que la tool s'executi, així que les crides rebutjades (scope incorrecte, error de validació) també consumeixen quota — això és anti-abús deliberat, d'acord amb el patró estàndard OAuth/REST.

Per pla, cada hora

Un sostre horari a nivell d'empresa per slug de pla. El pla Enterprise se salta aquest bucket completament.

Per client OAuth, global

Les apps OAuth comparteixen a més un bucket global per client de 1000 / min, de manera que una sola app que es comporti malament no pugui saturar el servidor a través de tots els seus usuaris.

Capçaleres de límit de peticions

Les respostes correctes porten el pressupost restant perquè puguis afluixar el ritme de manera proactiva:

Límits dels endpoints d'auth

Els endpoints OAuth tenen els seus propis límits, independents dels buckets d'MCP:

Errors de protocol i regles fiscals

Una cerca del protocol pot retornar -32602 quan no es resol el nom de l’eina; revisa el descobriment i els scopes de la credencial abans de reintentar. mcp_guardrail_violation és un rebuig de negoci 422 amb rule_id, guardrail_uri i subcodi. Llegeix el recurs fiscal indicat, corregeix els arguments i segueix la política d’idempotència de l’eina.