Skip to content

Status Codes and Errors

This page indexes the HTTP status codes and error codes of every MetaMiner Server (MMS) API endpoint and shows the error body each endpoint family returns.

Each endpoint page keeps its own responses table; this page is the cross-reference. Branch on the HTTP status first, then on the error code where the family has one.

Answers every endpoint can give

These come from the checks that run before an endpoint does its work: body size, then the API client token.

Status When Body and headers What to do
413 Request body over 64 KiB (checked before the token) {"status": "error", "message": "Request body too large"} Send a smaller body
401 API clients mode: no token, or not the token of an active client (unknown, rotated, revoked, expired) {"status": "error", "message": "Unauthorized"}, header WWW-Authenticate: Bearer Check the token and the client's status and expiry in MMA
401 Local only mode: a call from another machine {"error": "API_AUTH_REQUIRED", "code": "API_AUTH_REQUIRED", "message": "..."}, header WWW-Authenticate: Bearer Switch to API clients (see Authorization Modes)
503 The API clients cannot be checked: the Flow Scheduler is switched on but not running on that node, or the server's client file cannot be read {"error": "API_CLIENTS_UNAVAILABLE", "code": "API_CLIENTS_UNAVAILABLE", "message": "..."}, header Retry-After: 30 Retry. Start the Flow Scheduler on that node; through a load balancer the other node answers meanwhile.

MetaMiner never answers a failed client check with open access: it fails closed with 503.

Error body by endpoint family

Endpoint family Error body
/tab/credentials, /tab/credentials/status, /tab/credentials/sync {"status": "error", "message": "..."}. A change that is live but not saved answers 500 with status applied_not_persisted or persistence_unconfirmed. An unexpected error is 500 with a plain-text body.
/fss/v1/info, runflow, runtask, runs, runs/{runId} {"error": "<CODE>", "message": "..."}. RUN_FORBIDDEN also has code and flowLuid. When the Flow Scheduler refuses a run submit, its own answer is relayed and error may hold its text instead of a code.
/fss/v1/runs/{runId}/cancel {"runId": N, "error": "<CODE>", "message": "..."}
/fss/v1 tasks, chains, schedules, parameters, notifications Refused by MMS before the Flow Scheduler sees the call: {"error": "<CODE>", "message": "..."}. Answered by the Flow Scheduler: {"error": "<text>"}.
Any /fss/v1 write on a standby node 409 {"error": "NOT_LEADER", "message": "...", "leader": "<host>"}
/fss/v1/clients, /fss/v1/audit Refused by MMS: {"error": "<CODE>", "message": "..."}. With the Flow Scheduler switched on, store errors are {"error": "<text>"}; switched off, {"error": "BAD_REQUEST" or "NOT_FOUND" or "CONFLICT", "message": "..."}.
/fss/backup {"result": "error", "error": "<text>"}. 403 is {"error": "FORBIDDEN", "message": "..."}. A failed backup is 500 with the job fields and "result": "failed". An unexpected error is 500 with a plain-text body.

The deprecated /apitoken/rotate and its answers are on Rotate, Expire, Revoke.

Codes by HTTP status

Status Error code or result Endpoints Meaning
200 all Done. With wait, also a run that ended coalesced.
201 POST /fss/v1/clients Client created; the token is in the answer once
202 submitted runflow, runtask Run submitted; poll it
202 pending POST /fss/backup Backup still running after waitSeconds
400 BAD_REQUEST /fss/v1/* Missing or invalid field or parameter: env, site, flowLuid, task id, runMode, a status filter, limit, body not JSON
400 SITE_REQUIRED /fss/v1 lists A site-limited client listed without site=
400 (message) /tab/credentials Missing parameter; a login rejected by Tableau (nothing changed); a Tableau Cloud environment; a repository login without a repository connection
400 (message) /fss/v1/clients Invalid or reserved name, empty limit list, bad expiresAt; me/rotate under Local only
400 (message) POST /fss/backup Body is not JSON
401 all See Answers every endpoint can give
403 ENV_FORBIDDEN /fss/v1/* The client may not use that environment
403 SITE_FORBIDDEN /fss/v1/* The client may not use that site, or the site of the named object
403 SITE_SCOPE /fss/v1/* A site-limited client called a path not tied to one site
403 RUN_FORBIDDEN runflow, runtask The client's bound Tableau user may not run the flow, no user is bound, or trusted authentication is not set up
403 CANCEL_FORBIDDEN cancel Not a run this client started or owns
403 FORBIDDEN schedule writes, /fss/v1/clients, /fss/v1/audit, /fss/backup Needs an admin client without site limits (clients, audit, backup: without environment limits too)
403 (message) /tab/credentials* Not an admin client, site limits, or environment not allowed
404 ENV_NOT_FOUND /fss/v1/* env is not an environment enabled for the Flow Scheduler
404 TASK_NOT_FOUND, LINKED_TASK_NOT_FOUND runtask No such task or chain
404 FLOW_NOT_FOUND GET /fss/v1/runs/{runId}, runtask Read: no such run visible to this client. Run: the Flow Scheduler answered not found to the submit.
404 RUN_NOT_FOUND cancel No such run visible to this client
404 NOT_FOUND /fss/v1/* Unknown resource or object
404 (message) /fss/v1/clients/{name} No live client of that name (unknown or revoked)
404 (message) /tab/credentials Environment not configured on this node, or envName does not match
404 JOB_NOT_FOUND (in detail) /fss/backup/status/{id} Unknown backup job
409 NOT_LEADER every /fss/v1 write Sent to the standby node; leader names the leader
409 NOT_LEADER_OR_ACTIVE runtask, runflow The Flow Scheduler refused the submit, for example the task is already running
409 ALREADY_FINISHED cancel The run had already finished
409 (message) /fss/v1/clients A live client has that name, or the token is in use
409 (relayed) POST /fss/backup The backup could not start
413 all with a body Body over 64 KiB
500 INTERNAL /fss/v1/* Unexpected error
500 applied_not_persisted, persistence_unconfirmed /tab/credentials Active now; the save failed or was not confirmed within 10 seconds
500 failed POST /fss/backup The backup ran and failed
501 /tab/credentials The MMS configuration is encrypted
502 (run summary) runflow, runtask with wait The run failed or was cancelled
502 SUBMIT_FAILED, TABLEAU_UNAVAILABLE runflow, runtask The run could not be submitted
502 CANCEL_FAILED cancel The cancel did not go through
502 error /fss/backup The backup could not start, or MMS lost track of it during the wait
503 API_CLIENTS_UNAVAILABLE all See Answers every endpoint can give
503 (relayed) POST /fss/backup The backup could not start
504 (run summary) runflow, runtask with wait Still running at waitTimeoutSeconds; the run continues