> ## Documentation Index
> Fetch the complete documentation index at: https://embedded-apps.rollout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and troubleshooting

> The error codes the components and the API report, and what to check when apps don't show.

## Errors

Both components report errors to `onError` as `{ code, message }`. The API
returns the same codes in its error bodies.

Codes the components report on their own:

| Code | From | Meaning | What to do |
| - | - | - | - |
| `TOKEN_UNAVAILABLE` | Both | Your `getToken` threw or rejected. | Check your token endpoint. |
| `LAUNCH_FAILED` | Apps | Rollout couldn't be reached, or answered without a code. | Retry. |
| `MARKETPLACE_FAILED`, `ENABLEMENT_FAILED` | Marketplace | Listing the apps, or turning one on or off, failed the same way. | Retry. |

Codes from Rollout:

| Status | Code | Meaning |
| - | - | - |
| 401 | `NO_AUTHORIZATION_HEADER` | The request carried no token. |
| 401 | `INVALID_TOKEN` | The token's signature, expiry or format is invalid. |
| 401 | `INVALID_TOKEN_DATA` | A standard claim has the wrong type, such as a numeric `sub`. |
| 401 | `TENANT_NOT_FOUND` | `iss` isn't a Rollout tenant. |
| 401 | `EMBED_TOKEN_LIFETIME_EXCEEDED` | `exp` is more than an hour away. |
| 401 | `INVALID_EMBED_CLAIMS` | `rollout.com.embed` doesn't have the shape in [Claims](https://embedded-apps.rollout.com/build/user-tokens.md#claims). The message names the claim. |
| 403 | `TENANT_DEACTIVATED` | Your tenant is deactivated. |
| 403 | `EMBED_SCOPE_MISSING` | The token lacks the scope the request needs: `embed:render`, `embed:enable` or `embed:enable_org`. |
| 403 | `ORG_CLAIM_MISSING` | An org switch was used with a token that has no `embed.org`. |
| 403 | `ENABLEMENT_SCOPE_NOT_ALLOWED` | Turning an app on for a scope your marketplace doesn't allow. |
| 404 | `MARKETPLACE_NOT_FOUND` | No marketplace with this id belongs to the token's tenant. |
| 404 | `EMBEDDED_APP_NOT_FOUND` | The app isn't approved in this marketplace any more. |

The `message` explains the refusal in words, for your logs.

When Rollout refuses a token with a 401, the component calls `getToken` once
for a fresh one and retries. A second refusal is reported rather than retried.

A page whose origin isn't listed under **Pages that may show the apps** gets no
error: the browser refuses to load the Rollout frame, and logs a
`frame-ancestors` violation in its console.

## Troubleshooting

* **Nothing shows on the record.** Check that the app is approved, that the user
  (or their org) turned it on, and that `onAppsLoaded` lists it. If it's
  listed but not shown, the app's page isn't answering Rollout's handshake: ask
  its publisher.
* **An app turned on for the org doesn't show.** The render token needs the
  same `embed.org` as the token that turned it on.
* **The frame is refused in the console.** Add the page's exact origin under
  **Pages that may show the apps**.
* **Apps receive no name or stage for the person.** The token's
  `embed.person.id` has to equal the `record.id` you render. Mint the token for
  the record `getToken` is given.
* **The org switch doesn't appear.** The marketplace has to allow **For their
  org**, and the token needs `embed:enable_org` and `embed.org`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.