Where errors appear

  • Token endpoint: OAuth 2.0 error responses (RFC 6749) with error and error_description.
  • MCP endpoint: HTTP status codes for authentication and transport problems.
  • Tool calls: a tool result with isError: true and a structured error.

Token endpoint errors

  • invalid_request (400): installation_id is missing or malformed, or the body is not application/x-www-form-urlencoded.
  • invalid_client (401): client authentication failed, or the client has been revoked. Check the credentials; do not retry with the same values.
  • unsupported_grant_type (400): use client_credentials.
  • unauthorized_client (400): this client may not use the requested grant.
  • invalid_target (400): resource is missing or does not identify the MCP canonical URI.
  • invalid_grant (400): the installation is not active for this client. Unknown, foreign, revoked and expired installations deliberately return the same error. Contact the customer administrator.
  • invalid_scope (400): a requested scope is not in the installation grant.
  • slow_down (429): more than 30 token requests a minute for this client. Wait for the Retry-After header.
  • temporarily_unavailable (503): MCP access is not enabled in this environment.

MCP endpoint HTTP errors

  • 401: the token is missing, expired, has the wrong audience or is otherwise invalid. The WWW-Authenticate: Bearer resource_metadata=… header points to discovery metadata. Request a new token.
  • 421: the request reached the server under a host name it does not serve. Use the MCP host Encrisoft gave you.
  • 413: the request body is larger than 64 KB.

Tool errors

structuredContent of a tool error result
{
  "error": {
    "code": "rate_limited",
    "message": "Client quota exceeded",
    "retryAfterSeconds": 34,
    "correlationId": "…"
  }
}
  • unauthorized: the installation has been revoked or has expired, the client has been revoked, or the approving administrator is no longer an active owner or admin. Stop calling and contact the customer.
  • forbidden: the tool is not in the installation grant, or the approving administrator no longer holds the permission the tool needs.
  • rate_limited: the client quota is exceeded. Retry after retryAfterSeconds.
  • invalid_arguments: the Encrisoft API rejected the tool arguments. Arguments outside the input schema are normally rejected earlier, by MCP input validation.
  • upstream_unavailable: a temporary problem. Retry with exponential backoff.

Rate limits and quotas

Preview defaults, applied per partner client across all its installations:

  • 60 tool calls a minute and 5,000 a day. The daily window resets at midnight UTC.
  • 30 token requests a minute.
  • Access tokens default to 10 minutes; use the token response’s expires_in value.

Encrisoft may set different limits for an individual client during the preview.

Retrying safely

  • Reuse a token until shortly before it expires instead of requesting one per call.
  • Respect Retry-After and retryAfterSeconds.
  • Retry upstream_unavailable with exponential backoff and jitter.
  • Do not retry unauthorized, forbidden, invalid_arguments, invalid_client or invalid_grant without changing something first.

Contacting support

Include the X-Correlation-Id from the response or the correlationId from the error. Never include tokens or secrets.