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 JSON-RPC equivalent, amb el code i l'http_status de v1 conservats a data.

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.

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 (sempre dins del rang -32099..-32000 definit per la implementació, o -32603 per a errors interns).
• 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", "clients: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: