# Error codes

Every error code the API, the embed SDK, a workflow check and the preflight check can return.

Every API error has the same body. Branch on `error.code`. The message is written for a person and may change. Some codes add a `details` object, such as `{"reason": "revoked"}`.

```json
{ "error": { "code": "CONCURRENCY_LIMIT", "message": "…" } }
```

## The request · 400, 405, 422

- 400 `INVALID_BODY` Fix the request

  The body is not valid JSON, or not the shape this call takes.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options).

- 400 `NOT_SUPPORTED` Fix the request

  This app declares no dynamic fields or options.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options).

- 400 `VALIDATION_ERROR` Fix the request

  A parameter or the body is not valid; the message names it.

  From [List runs](https://docs.gorunner.io/api/runs/list-runs), [Get a run](https://docs.gorunner.io/api/runs/get-run), [Delete a run](https://docs.gorunner.io/api/runs/delete-run) and 115 more.

- 405 `METHOD_NOT_ALLOWED` Fix the request

  The path exists, but not with this method.

  From [Deliver to a webhook](https://docs.gorunner.io/api/runs/deliver-webhook).

- 422 `CONNECTION_MISMATCH` Fix the request

  A connection named for a slot is for another service (`details.slot`).

  From [Make a workflow from a template](https://docs.gorunner.io/api/templates/use-template), [Preview using a template](https://docs.gorunner.io/api/templates/preview-template-use), [Install a template (Partner API)](https://docs.gorunner.io/embed/api/workflows/install-workflow).

- 422 `CONNECTION_TEST_FAILED` Fix the request

  With `"test": true`, the service refused the settings when tested, so nothing was saved (`details.cause` says why). See [A connection stopped working](https://docs.gorunner.io/build/a-connection-stopped-working).

  From [Create a connection](https://docs.gorunner.io/api/connections/create-connection), [Rename or update a connection](https://docs.gorunner.io/api/connections/update-connection), [Create a connection](https://docs.gorunner.io/api/connections/create-connection).

- 422 `INVALID_ORIGIN` Fix the request

  The website can’t be allowed as written, or is a wildcard. A customer’s website is one exact address.

  From [Replace an account’s websites (Partner API)](https://docs.gorunner.io/embed/api/websites/put-account-websites), [Allow a website for one account (Partner API)](https://docs.gorunner.io/embed/api/websites/add-account-website), [Allow a website (Partner API)](https://docs.gorunner.io/embed/api/websites/add-website).

- 422 `PIECE_NOT_ALLOWED` Fix the request

  A step uses an app this workspace may not use. The message names the step. See [Switches](https://docs.gorunner.io/embed/switches).

  From [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow), [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Go back to a version](https://docs.gorunner.io/api/publish/restore-workflow-version) and 10 more.

- 422 `RETURN_URL_NOT_ALLOWED` Fix the request

  The return address is not on an allowed website.

  From [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft), [Start a connection sign-in from your own button (Partner API)](https://docs.gorunner.io/embed/api/connections/start-connection-sign-in).

- 422 `SECRETS_REQUIRED` Fix the request

  The change moves a where field (a host, server, port, database, URL or connection string) while a stored secret was left blank.

  From [Test sign-in details before saving](https://docs.gorunner.io/api/connections/test-connection-draft), [Rename or update a connection](https://docs.gorunner.io/api/connections/update-connection).

- 422 `SIGN_IN_ADDRESS_NOT_ALLOWED` Fix the request

  The AI app sign-in address is not on a website allowed for the installation or for this account.

  From [Create or update an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/put-account).

- 422 `TOO_MANY_WEBSITES` Fix the request

  The list is full: 20 websites for one account, 200 for the installation (`details.max` says which).

  From [Replace an account’s websites (Partner API)](https://docs.gorunner.io/embed/api/websites/put-account-websites), [Allow a website for one account (Partner API)](https://docs.gorunner.io/embed/api/websites/add-account-website), [Allow a website (Partner API)](https://docs.gorunner.io/embed/api/websites/add-website).

- 422 `VALIDATION_ERROR` Fix the request

  A rule the body breaks (the message names it), or an Idempotency-Key reused with a different body.

  From [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow), [Get a new webhook address](https://docs.gorunner.io/api/publish/rotate-workflow-webhook-token), [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow) and 29 more.

## Access · 401, 403

- 401 `EMBED_SESSION_ENDED` Fix the request

  The login code’s person no longer has that access (`details.reason` says why).

  From [Start a session (Partner API)](https://docs.gorunner.io/embed/api/sign-in/start-session), [End a session (Partner API)](https://docs.gorunner.io/embed/api/sign-in/end-session), [Turn switches off for a session (Partner API)](https://docs.gorunner.io/embed/api/sign-in/narrow-session) and 1 more.

- 401 `INVALID_CODE` Fix the request

  The code is missing, unknown, used or expired.

  From [Start a session (Partner API)](https://docs.gorunner.io/embed/api/sign-in/start-session).

- 401 `TOKEN_ENDED` Fix the request

  A token made inside a partner’s product stopped working: it was revoked or expired, its maker left or lost the editor role, or its account or workspace was deleted (`details.reason` says which). Make a new token. See [Tokens and AI apps](https://docs.gorunner.io/embed/tokens-and-ai-apps).

  From any call with a token made inside a partner’s product.

- 401 `UNAUTHORIZED` Fix the request

  The token is missing, expired or revoked.

  From any call that needs a token.

- 403 `ACCOUNT_SUSPENDED` Fix the request

  The workspace’s account is suspended. Nothing new starts until it is resumed, and its data is kept. See [Usage, suspension and deletion](https://docs.gorunner.io/embed/usage-suspension-deletion).

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 21 more.

- 403 `BROWSER_REQUIRED` Fix the request

  Signing in needs a person in a browser. An API token signs a connection in again through Start a sign-in for a new connection, with connectionId and returnUrl.

  From [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft), [Start a sign-in for a connection](https://docs.gorunner.io/api/connections/start-connection-oauth2).

- 403 `EMBED_NOT_ALLOWED` Fix the request

  Only an embedded session can do this. An AI app’s connection or a token can’t, and the embedded view can’t reach this part of the API.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 24 more.

- 403 `EMBED_NOT_AVAILABLE` Fix the request

  Embedding is not licensed here, or sign-in is off. The login code is not used up.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 25 more.

- 403 `EMBED_NOT_LICENSED` Fix the request

  This installation's license does not include embedding. See [Your license](https://docs.gorunner.io/self-host/license).

  From [Make a login code (Partner API)](https://docs.gorunner.io/embed/api/sign-in/issue-login-code), [List accounts (Partner API)](https://docs.gorunner.io/embed/api/accounts/list-accounts), [Create or update an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/put-account) and 51 more.

- 403 `FEATURE_OFF` Fix the request

  In an embedded session, the switch this call needs is off (for example folders). See [Switches](https://docs.gorunner.io/embed/switches).

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 23 more.

- 403 `FORBIDDEN` Fix the request

  The token lacks the permission this call needs.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 11 more.

- 403 `IP_NOT_ALLOWED` Fix the request

  The key's address allow-list does not include the caller.

  From [Make a login code (Partner API)](https://docs.gorunner.io/embed/api/sign-in/issue-login-code), [List accounts (Partner API)](https://docs.gorunner.io/embed/api/accounts/list-accounts), [Create or update an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/put-account) and 51 more.

- 403 `KEEL_CLICK_REQUIRED` Fix the request

  Keel tried to publish without a person pressing its card. A person must press it.

  From [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow), [Unpublish a workflow](https://docs.gorunner.io/api/publish/unpublish-workflow).

- 403 `MANAGED_CONNECTION` Fix the request

  The partner manages that connection, so it can’t be changed here.

  From [Test sign-in details before saving](https://docs.gorunner.io/api/connections/test-connection-draft), [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft), [Rename or update a connection](https://docs.gorunner.io/api/connections/update-connection) and 4 more.

- 403 `ORG_LIMIT` Fix the request

  The license’s organization limit is reached. See [Your license](https://docs.gorunner.io/self-host/license).

  From [Make a login code (Partner API)](https://docs.gorunner.io/embed/api/sign-in/issue-login-code), [Create or update an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/put-account), [Restore an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/restore-account) and 4 more.

- 403 `ORIGIN_NOT_ALLOWED` Fix the request

  The page is not one of the allowed websites. The login code is not used up.

  From [Start a session (Partner API)](https://docs.gorunner.io/embed/api/sign-in/start-session).

- 403 `PIECE_NOT_ALLOWED` Fix the request

  The app is not one this workspace may use. See [Switches](https://docs.gorunner.io/embed/switches).

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 4 more.

- 403 `TOKEN_SURFACE_OFF` Fix the request

  The token wasn’t made to work here: with the API, or with AI apps (`details.surface` says which).

  From any call with a token made inside a partner’s product.

- 403 `WORKSPACE_LIMIT` Fix the request

  The license’s workspace limit is reached. See [Your license](https://docs.gorunner.io/self-host/license).

  From [Make a login code (Partner API)](https://docs.gorunner.io/embed/api/sign-in/issue-login-code), [Create or update an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/put-account), [Sign a person in for an AI app (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/complete-oauth-request) and 5 more.

## Not found or in conflict · 404, 409

- 404 `ALREADY_ANSWERED` Fix the request

  An approval link that was already answered. The run has moved on.

  From an approval link, asked for JSON.

- 404 `NOT_FOUND` Fix the request

  Nothing with that ID in this workspace, or a mistyped path.

  From [Get a run](https://docs.gorunner.io/api/runs/get-run), [Delete a run](https://docs.gorunner.io/api/runs/delete-run), [Stream a run](https://docs.gorunner.io/api/runs/stream-run) and 96 more.

- 404 `OAUTH_REQUEST_NOT_FOUND` Fix the request

  No such sign-in request, or it expired.

  From [Read a sign-in request (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/get-oauth-request), [Sign a person in for an AI app (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/complete-oauth-request), [Turn a sign-in request down (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/deny-oauth-request).

- 404 `STEP_NOT_FOUND` Fix the request

  With step: the run has no step of that name. The message lists the ones it has.

  From [Get a run](https://docs.gorunner.io/api/runs/get-run).

- 404 `TIMED_OUT` Fix the request

  An approval link whose wait timed out before anyone answered.

  From an approval link, asked for JSON.

- 409 `ACCOUNT_DELETED` Fix the request

  The workspace’s account was deleted. Restore it first. See [Usage, suspension and deletion](https://docs.gorunner.io/embed/usage-suspension-deletion).

  From [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft), [Open a sign-in in this tab](https://docs.gorunner.io/api/connections/launch-connection-oauth2-here) and 27 more.

- 409 `ACCOUNT_NOT_DELETED` Fix the request

  The account is not deleted, so there is nothing to restore.

  From [Restore an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/restore-account).

- 409 `ACCOUNT_SUSPENDED` Fix the request

  The account is suspended, so the run can’t be decided or run again now. See [Usage, suspension and deletion](https://docs.gorunner.io/embed/usage-suspension-deletion).

  From [Approve or reject a held run](https://docs.gorunner.io/api/runs/decide-run), [Run a run again (Partner API)](https://docs.gorunner.io/embed/api/runs/rerun-run).

- 409 `ALREADY_ANSWERED` Fix the request

  The approval was already answered.

  From [Approve or reject a held run](https://docs.gorunner.io/api/runs/decide-run).

- 409 `ALREADY_RETRIED` Fix the request

  In Run many runs again’s results: that run already has a retry that worked or is still going, so it was left out.

  From [Run many runs again](https://docs.gorunner.io/api/runs/rerun-runs-bulk).

- 409 `BUSY` Fix the request

  Something else held the thing this call needs, and the call gave up waiting. Nothing was done. Try again.

  From [Delete a workflow](https://docs.gorunner.io/api/workflows/delete-workflow), [Make a login code (Partner API)](https://docs.gorunner.io/embed/api/sign-in/issue-login-code), [Create or update an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/put-account) and 2 more.

- 409 `CONFLICT` Fix the request

  The request clashes with the current state. If a request with the same Idempotency-Key is still in progress, retry shortly.

  From [Delete a run](https://docs.gorunner.io/api/runs/delete-run), [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow), [Unpublish a workflow](https://docs.gorunner.io/api/publish/unpublish-workflow) and 26 more.

- 409 `DEFAULT_WORKSPACE` Fix the request

  An account’s default workspace can’t be deleted.

  From [Delete a workspace (Partner API)](https://docs.gorunner.io/embed/api/workspaces/delete-workspace), [Delete a workspace](https://docs.gorunner.io/embed/api/workspaces/delete-workspace).

- 409 `EDITING_ELSEWHERE` Fix the request

  The workflow is being edited in another tab.

  From [Update a workflow’s draft](https://docs.gorunner.io/api/workflows/update-workflow).

- 409 `KEEL_PUBLISH_STALE` Fix the request

  A click on the assistant's publish card named no review, or a draft or base version that has moved since the card was shown.

  From [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow).

- 409 `NAME_TAKEN` Fix the request

  A folder with that name is already in that place, or a workspace with that name is already in the organization.

  From [Create a folder](https://docs.gorunner.io/api/folders/create-folder), [Rename or move a folder](https://docs.gorunner.io/api/folders/update-folder), [Create a folder](https://docs.gorunner.io/api/folders/create-folder) and 1 more.

- 409 `NOT_A_MEMBER` Fix the request

  With provision false, the person is not a member of the workspace.

  From [Sign a person in for an AI app (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/complete-oauth-request).

- 409 `NOT_WAITING` Fix the request

  The run is not waiting for an approval.

  From [Approve or reject a held run](https://docs.gorunner.io/api/runs/decide-run).

- 409 `OAUTH_REQUEST_ACCOUNT_MISMATCH` Fix the request

  The account is not the one the sign-in request is for. The request is not used up.

  From [Sign a person in for an AI app (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/complete-oauth-request).

- 409 `OAUTH_REQUEST_DONE` Fix the request

  The sign-in request was already completed or turned down.

  From [Sign a person in for an AI app (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/complete-oauth-request), [Turn a sign-in request down (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/deny-oauth-request).

- 409 `RENEW_REFUSED` Fix the request

  The session can’t be renewed (`details.reason` says why). Ask your server for a new login code.

  From [Renew a session (Partner API)](https://docs.gorunner.io/embed/api/sign-in/renew-session).

- 409 `RESTORE_EXPIRED` Fix the request

  The account was deleted more than 30 days ago and can no longer be restored.

  From [Restore an account (Partner API)](https://docs.gorunner.io/embed/api/accounts/restore-account).

- 409 `ROLE_DIFFERS` Fix the request

  With provision false, the role is not the person’s role there.

  From [Sign a person in for an AI app (Partner API)](https://docs.gorunner.io/embed/api/ai-apps/complete-oauth-request).

- 409 `RUN_NOT_FINISHED` Fix the request

  The run is queued, running or held. Cancel it first, or wait.

  From [Run a run again](https://docs.gorunner.io/api/runs/rerun-run), [Run many runs again](https://docs.gorunner.io/api/runs/rerun-runs-bulk).

- 409 `SIGNIN_NOT_PENDING` Fix the request

  The sign-in was already opened or has ended, or isn’t a tab sign-in. Start it again.

  From [Open a sign-in in this tab](https://docs.gorunner.io/api/connections/launch-connection-oauth2-here).

- 409 `TOKEN_LIMIT` Fix the request

  The workspace already has 25 live tokens.

  From [Make a token (Partner API)](https://docs.gorunner.io/embed/api/tokens/create-token).

- 409 `WEBSITE_EXISTS` Fix the request

  The list already holds it.

  From [Allow a website for one account (Partner API)](https://docs.gorunner.io/embed/api/websites/add-account-website), [Allow a website (Partner API)](https://docs.gorunner.io/embed/api/websites/add-website).

- 409 `WORKFLOW_NOT_LIVE` Fix the request

  A production run whose workflow is paused or a draft. No run is started.

  From [Run a run again](https://docs.gorunner.io/api/runs/rerun-run).

- 409 `WORKFLOW_NOT_PUBLISHED` Fix the request

  The workflow is not on, so it has nothing published to run.

  From [Run a run again (Partner API)](https://docs.gorunner.io/embed/api/runs/rerun-run).

## The body · 413, 415

- 413 `PAYLOAD_TOO_LARGE` Fix the request

  The body is larger than this call accepts.

  From [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Deliver to a webhook](https://docs.gorunner.io/api/runs/deliver-webhook), [Create a workflow](https://docs.gorunner.io/api/workflows/create-workflow) and 33 more.

- 415 `INVALID_CONTENT_TYPE` Fix the request

  A Content-Type other than application/json (leaving it out is fine).

  From any POST, PUT or PATCH to the API with a Content-Type other than application/json.

## Limits · 429

- 429 `CONCURRENCY_LIMIT` Retry later

  The workflow is at its concurrency limit and is set to Refuse. Try again when a run finishes. See [Limit runs at once](https://docs.gorunner.io/build/runs-at-once).

  From [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Deliver to a webhook](https://docs.gorunner.io/api/runs/deliver-webhook), [Run a run again (Partner API)](https://docs.gorunner.io/embed/api/runs/rerun-run) and 1 more.

- 429 `RATE_LIMITED` Retry later

  Too many requests from this caller (an API token, a session or an embed session) or this address. Retry-After says when to try again.

  From any call, once the caller’s requests for the minute are used up.

- 429 `RUNS_WAITING_LIMIT` Retry later

  Too many runs are already waiting in line, for the organization or for this workflow. Try again later. See [Limit runs at once](https://docs.gorunner.io/build/runs-at-once).

  From [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Deliver to a webhook](https://docs.gorunner.io/api/runs/deliver-webhook), [Run a run again (Partner API)](https://docs.gorunner.io/embed/api/runs/rerun-run) and 1 more.

- 429 `TOO_MANY_STREAMS` Retry later

  This person or token already follows 50 runs on this server. Retry-After says when to try again.

  From [Stream a run](https://docs.gorunner.io/api/runs/stream-run).

## The server · 500, 503

- 500 `DELETE_FAILED` Retry

  The delete did not happen, and the workflow is still there. Try again.

  From [Delete a workflow](https://docs.gorunner.io/api/workflows/delete-workflow).

- 500 `ENQUEUE_FAILED` Retry

  The approval could not be handed to a worker. The run is still held.

  From [Approve or reject a held run](https://docs.gorunner.io/api/runs/decide-run).

- 500 `INTERNAL_ERROR` Retry

  Something failed on the server. Try again.

  From [List runs](https://docs.gorunner.io/api/runs/list-runs), [List waiting runs](https://docs.gorunner.io/api/runs/list-waiting-runs), [Delete a run](https://docs.gorunner.io/api/runs/delete-run) and 127 more.

- 500 `RESOLVE_FAILED` Retry

  The Sub-flow step’s inputs, or the list of workflows to choose from, could not be read.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options).

- 503 `ACCOUNT_SUSPENDED` Retry

  A webhook or form of a suspended account. Nothing ran. Retry-After says an hour. See [Usage, suspension and deletion](https://docs.gorunner.io/embed/usage-suspension-deletion).

  From a webhook or form address.

- 503 `BUSY` Retry

  This server holds as much request data as it can right now. Nothing was done. Retry after Retry-After.

  From any call or webhook whose body doesn’t fit, and any read of a run’s data, while the server is full.

- 503 `NO_VERDICT` Retry

  With `"test": true`, no worker could test the connection, so nothing was saved. Try again (`details.reason` says why).

  From [Create a connection](https://docs.gorunner.io/api/connections/create-connection), [Rename or update a connection](https://docs.gorunner.io/api/connections/update-connection), [Create a connection](https://docs.gorunner.io/api/connections/create-connection) and 1 more.

- 503 `PAUSED` Load a license

  A self-hosted installation without a valid license is paused. Nothing is read, written or run. An API call gets no Retry-After: load a license. A webhook or form gets a Retry-After of an hour. See [When a license ends](https://docs.gorunner.io/self-host/license-ends).

  From any call with an API token made in GoRunner, and any webhook or form address, on a paused self-hosted installation.

- 503 `PIECES_UNAVAILABLE` Retry

  GoRunner couldn’t check which apps may run. Nothing started.

  From [List apps](https://docs.gorunner.io/api/apps/list-apps), [Get an app](https://docs.gorunner.io/api/apps/get-app), [Get an action’s fields](https://docs.gorunner.io/api/apps/get-app-action) and 27 more.

- 503 `SERVICE_UNAVAILABLE` Retry

  The database or Redis didn’t answer, so the request wasn’t checked and nothing was done. Retry after Retry-After.

  From any call whose token can’t be looked up because the database or Redis didn’t answer.

- 503 `STATE_UNAVAILABLE` Retry

  The account's state could not be read, so nothing was started.

  From [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft), [Start a sign-in for a connection](https://docs.gorunner.io/api/connections/start-connection-oauth2) and 3 more.

- 503 `STORAGE_UNAVAILABLE` Retry

  A webhook that answers in the same call: the run finished, but its step output couldn’t be read back from storage. The run is intact. Retry, or read it with Get a run.

  From [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow), [Deliver to a webhook](https://docs.gorunner.io/api/runs/deliver-webhook).

- 503 `UNAVAILABLE` Retry

  This server can’t do it now: no Redis to signal a cancel or record a sign-in, or the installation’s OAuth app for the service can’t be read.

  From [Cancel a run](https://docs.gorunner.io/api/runs/cancel-run), [Create a connection](https://docs.gorunner.io/api/connections/create-connection), [Rename or update a connection](https://docs.gorunner.io/api/connections/update-connection) and 3 more.

- 503 `WORKER_UNAVAILABLE` Retry

  No worker is checked in.

  From [Get a field’s sub-fields](https://docs.gorunner.io/api/apps/resolve-dynamic-properties), [Get a field’s options](https://docs.gorunner.io/api/apps/resolve-dynamic-options), [Get a trigger’s sample data](https://docs.gorunner.io/api/apps/get-trigger-sample) and 2 more.

The embed SDK’s codes, from `mount()`, the `error` event, and its methods.

## When mounting, or after

- `not_allowed_here` mount() or the error event

  Your page's origin is not one of the installation's allowed websites (Platform › Partner keys › Allowed websites), or the page has no web origin at all (a file: page). The browser would block the frame, so the SDK refuses before it is made.

- `licence` mount() or the error event

  The installation's license does not include Embed, or the installation is paused because its license ended.

- `unavailable` mount() or the error event

  Embedding is turned off on the installation (sign-in is off), or nothing is switched on for this person, so there is no page to show them.

- `code_failed` mount() or the error event

  getCode threw, returned something that is not a code, or did not settle in time. The message carries your error's message.

- `code_expired` mount() or the error event

  The installation refused the code, and the fresh one the frame asked for too: used, or older than 60 seconds. Check that your server asks for a new code on every call rather than handing out a cached one.

- `access_ended` mount() or the error event

  The person no longer has access to this account: they were removed, or the account or the workspace was deleted. A new code for the same account will not help.

- `account_suspended` mount() or the error event

  This account is suspended: everything can be read, nothing can be changed or run. A warning: the frame stays open, and the error event has fatal: false.

- `not_available` mount() or the error event

  The page you mounted is switched off for this person: “The page this embed was asked to open (/overview) is switched off here.” Mount without it, or with one that is on. The frame says this, so every SDK version gets it.

- `session_failed` mount() or the error event

  The session could not be renewed: the host page did not hand over a new sign-in code.

- `unreachable` mount() or the error event

  The frame could not reach the installation while signing in.

- `crashed` mount() or the error event

  The frame hit an error it could not recover from.

- `version_mismatch` mount() or the error event

  The frame and the SDK share no protocol version. Load /embed.js from the installation, or upgrade the package.

- `timeout` mount() or the error event

  The frame did not answer within timeoutMs. The commonest cause is your page's Content-Security-Policy not allowing the installation in frame-src. For a method, the frame did not reply within ten seconds.

- `container_not_found` mount() or the error event

  No element matches the container selector, or the element given is not in the page.

- `invalid_options` mount() or the error event

  An option is missing or not what it should be; the message names it. Methods use it for an argument they cannot take, such as a theme that is not one.

- `unmounted` mount() or the error event

  unmount() was called, or the React component went away, before the mount finished. For a method: the instance was unmounted.

## From a method

- `not_ready` a method

  The embed is not ready: still mounting, reconnecting, or ended.

- `not_allowed` a method

  The page is switched off for this person, or making connections is not available to them.

- `not_configured` a method

  Connecting that service is not set up on the installation (no OAuth app for its provider).

- `invalid_page` a method

  What you passed to navigate or switchAccount is not a page.

- `piece_not_found` a method

  connect named a service the installation does not have, or an app id that is not one.

- `busy` a method

  A connection dialog is already open, or the embed is already signing in.

- `invalid_appearance` a method

  setAppearance was given something that is not a settings object, one over 16 KB, or one the frame refuses: a value outside the appearance settings, a font service's stylesheet, or an uploaded face whose file is not at the installation's own address or on your page's own website. An appearance in mount() that the frame refuses is ignored, and the embed shows your installation's look.

- `unsupported` a method

  The frame answered without the result the method expects — an installation of another release than this SDK.

- `frame_reloaded` a method

  The frame document reloaded, or the embed switched account, while the call was waiting for its reply. Call it again once the embed is ready.

[Check a definition](https://docs.gorunner.io/api/workflows/validate-workflow-definition) answers with `diagnostics`, and [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow) refuses with the first blocking one. Each has a `code`, a `severity`, and where it points: `path`, `step` and `field`. Many also list the allowed values in `alternatives`.

## Errors

- `invalid_definition`

  The definition can’t be read as a workflow.

- `unknown_field`

  The definition has a key the format doesn’t have. Nothing else is checked until it’s gone.

- `invalid_tree`

  The steps don’t form a valid tree. The message says where.

- `no_trigger`

  The workflow has no trigger.

- `no_steps`

  The workflow has no steps after its trigger.

- `unknown_piece` `pieceId`

  No app has that id here.

- `piece_not_triggerable` `pieceId`

  The app has no triggers, so it can’t start a workflow.

- `unknown_trigger` `actionId`

  The app has no trigger with that id at that version.

- `no_piece_selected` `pieceId`

  A step has no app chosen.

- `no_action_selected` `actionId`

  A step has no action chosen.

- `unknown_action` `actionId`

  The app has no action with that id at that version.

- `unknown_piece_version` `pieceVersion`

  A step is pinned to an app version no worker runs. It would fail rather than run another version.

- `piece_not_allowed` `pieceId`

  The workspace may not use this app.

- `missing_connection` `connectionId`

  A step or trigger that needs a connection has none.

- `connection_not_found` `connectionId`

  The step names a connection this workspace doesn’t have.

- `connection_wrong_piece` `connectionId`

  The step names a connection made for another app.

- `missing_required_config`

  A required field is empty.

- `condition_operator_missing`

  A condition has no operator.

- `unknown_operator`

  A condition uses an operator that doesn’t exist. alternatives lists the real ones.

- `unknown_step_reference`

  An expression reads a step that isn’t in the workflow.

- `step_name_too_long`

  A step’s name or display name is over 255 characters. If the workflow being replaced already holds that name, this is a warning: a run that reaches the step can’t save its steps.

- `unbalanced_expression`

  A field has an unclosed {{ or a }} that closes nothing.

- `wait_not_on_main_chain`

  A step that waits for an answer is inside a branch or a loop. Move it to the main line of steps.

- `subflow_self` `workflow_id`

  A Sub-flow step runs the workflow it is in.

- `tool_returns_unknown_step` `returns`

  An MCP Tool trigger returns a step that isn’t in the workflow.

- `catalog_unavailable`

  No worker has reported which apps it runs, so publishing is refused. When you only check, it is a note: the app checks were skipped.

## Warnings

- `condition_value_missing`

  The operator compares against a value, but none is set.

- `invalid_enum_value`

  A value isn’t one of the field’s options.

- `invalid_regex`

  A pattern isn’t a regular expression the engine can read. Lookarounds and backreferences aren’t supported.

- `unknown_config_field`

  The action has no such field, so it’s ignored.

- `error_arm_not_enabled` `onError`

  A step has error steps, but its error mode isn’t errorPath, so they never run.

## Notes

- `legacy_error_handling`

  A step keeps retry and timeout settings from the old Advanced section. They still apply.

The exit status of the preflight check (`check`), which setup and every update run first.

## Exit statuses

- 0 `exit 0`

  Nothing is wrong. Warnings are allowed.

- 1 `exit 1`

  At least one problem. Each one names the line to change.

- 2 `exit 2`

  The command line itself was wrong.

- 4 `exit 4`

  At least one problem that protects data GoRunner already holds, such as an encryption key that is not the installation’s. Setup, deploy and a container’s start never go past it, even when told to skip the check.

How to handle them: see [Errors in the API](https://docs.gorunner.io/api/errors), [The SDK](https://docs.gorunner.io/embed/sdk) and [The preflight check](https://docs.gorunner.io/self-host/preflight-check).

Source: https://docs.gorunner.io/errors