Errors & retries

REST errors use a stable machine-readable code and a request reference:

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "The shared connector request limit has been reached.",
    "requestId": "example-request-reference"
  }
}

The example reference is illustrative. The actual response also carries X-Request-Id.

Error codes

HTTP	Code	Action
400	INVALID_INPUT	Check parameter names, types and bounds
400	INVALID_JSON	Send valid JSON
400	BATCH_DISABLED	Send one MCP message per request
401	AUTH_REQUIRED	Send a connector access token in a bearer header
401	INVALID_TOKEN	Obtain a valid, unexpired connector access token
403	PRO_REQUIRED	Active Pro is required for the account pilot
403	ACCOUNT_INACTIVE	Resolve account access with Fisk
403	ACCESS_REVOKED	Reconnect and obtain fresh consent
403	CLIENT_DISABLED	Ask Fisk to confirm the approved client
403	ORIGIN_DENIED	Use an approved browser origin or your backend
403	HOST_DENIED	Use the canonical api.fisk.co.tz hostname
404	NOT_FOUND	The requested published resource is unavailable
405	METHOD_NOT_ALLOWED	Use the supported method; MCP uses POST
413	BODY_TOO_LARGE	Reduce the request body
429	RATE_LIMIT, DAILY_LIMIT	Wait for the indicated interval or reset
429	SEARCH_RATE_LIMIT, SEARCH_DAILY_LIMIT	Respect the shared keyword-search budget
429	CAPACITY_LIMIT	Shared pilot capacity is exhausted; wait
503	PILOT_DISABLED	Environment data access is not enabled
503	DATA_UNAVAILABLE, SERVICE_UNAVAILABLE	Retry later with a bounded policy

Retry policy

Honor Retry-After in seconds when the response provides it.

For a transient network failure or HTTP 503, use a small maximum number of retries with exponential backoff and jitter. Avoid retrying an entire multi-company workflow when only one request failed.

Do not automatically retry 400, 403 or 404. A 401 may be resolved with one coordinated token refresh; repeated refresh failures require reconnection.

MCP errors

Tool-level failures set isError: true. Handle the included error code rather than asking an assistant to guess from the message. Transport or authorization failures may occur before the tool runs.

Support

Send dennis@fisk.co.tz the request ID, approximate time, endpoint or tool name, and observed error code.

Do not include bearer tokens, refresh tokens, passwords or private account data.