Troubleshooting & FAQ

Common errors and solutions

Use this page to diagnose common authentication, Flow, integration, model, and Surface errors.

Authentication errors

Invalid API key

An invalid or missing credential produces a 401 Unauthorized response. An API Surface can return Invalid API key for a key that does not match an active key on that Surface.

Check these causes:

  • The key is expired, deleted, or inactive.
  • The key belongs to a different Surface.
  • The request uses the wrong key type or prefix.

To fix an API key error, follow these steps:

  1. Confirm that the request sends the key in the Authorization header as a Bearer token. For an API Surface, you can also use the X-API-Key header.
  2. For the Runtype API, open Settings > API. Use a key that matches the request environment. Management keys use the rt_live_ or rt_test_ prefix.
  3. For an API Surface, open Keys and use a papi_ key issued by that Surface. Every Surface accepts both Test and Production keys.
  4. Regenerate a management key in Settings > API, or create a replacement Surface key when the current key is expired or exposed.

Origin not allowed

The chat API returns 403 with Origin not allowed when the page origin does not match the client token’s allowedOrigins list.

To fix an origin error, follow these steps:

  1. Open the Product that contains the chat Surface.
  2. On the Surface panel, click Auth.
  3. Add the full page origin to Allowed Origins, including its scheme, hostname, and port when required.
  4. Confirm that the Surface is Active and has at least one enabled Capability.

Flow execution errors

Review the execution details in Logs when a Flow returns an error.

Step timeout

The default step timeout is 5 minutes, and the default Flow timeout is 15 minutes.

To diagnose a timeout, follow these steps:

  1. Open Logs and inspect the slow step’s duration and timeout value.
  2. Reduce the work that the step performs.
  3. Change the step or Flow timeout when the work needs more time.

Undefined variable

If you see Cannot read property 'output' of undefined, the Flow references an outputVariable that does not exist or does not run before the reference.

Use these checks to resolve the error:

  1. Confirm that the reference matches the earlier step’s outputVariable spelling.
  2. Confirm that the referenced step runs on the selected conditional branch before the later reference.
  3. Add a conditional check or a default value with ?? when the variable can be missing.

Rate limit exceeded

Runtype returns 429 when your requests exceed a plan’s execution burst rate. The Retry-After header tells you when to retry. AI model providers can apply separate limits to model requests.

To handle a rate limit, follow these steps:

  1. Read the Retry-After header from the response.
  2. Retry the request after the specified interval.
  3. Lower concurrency or add delay steps for large workloads.
  4. Use your own provider key when platform-key throughput is the constraint.

Flow validation errors

Conditional nesting too deep

The validator rejects conditional steps that exceed 10 nested levels. It returns this message: Conditional steps may nest at most 10 levels deep. The error code is CONDITIONAL_NESTING_TOO_DEEP.

To fix the validation error, use one of these approaches:

  1. Flatten nested conditionals by combining conditions with && and || in one conditional.
  2. Add a transform-data step that calculates the branching result, then reference that result in one conditional.

Integration errors

Slack message failed

If an Agent’s Slack tool cannot send a message, check the Slack app, bot token, target channel, and Agent tool configuration.

Use these checks:

  • Confirm that the Slack app is installed in the workspace and that the bot can post to the channel.
  • Confirm that the bot token in Settings > Integrations matches the token from the Slack app’s OAuth & Permissions page.
  • Confirm that the Agent includes the Slack tool that sends messages.

Firecrawl scraping failed

If a Firecrawl request fails, check the URL, credentials, and request parameters.

Use these checks:

  • Confirm that the page URL is valid and reachable.
  • If you use your own Firecrawl key, verify it in Settings > Integrations.
  • If you use the Firecrawl Agent tool, set waitFor between 0 and 30000 milliseconds.

Model errors

Model not available

Only configured models appear in model pickers. A model becomes unavailable when you remove its configuration or when its provider credentials are missing or invalid.

To make a model available, follow these steps:

  1. Open Settings > Models and find the model in the catalog or My Models.
  2. Add the model configuration or enable the model on its provider card.
  3. If the model uses your own provider key, open Providers and verify the key.
  4. Select a configured model in the Flow or Agent step.

Context length exceeded

If a provider returns Maximum context length exceeded, reduce the prompt or input, summarize the input, or select a model with a larger context length.

Use the context length filter in Settings > Models to find models that support larger inputs.

Surface errors

Chat widget not appearing

The chat widget needs the generated script-tag snippet, an active client token, an active Surface, and a matching page origin.

To troubleshoot the widget, follow these steps:

  1. Paste the generated snippet before the closing </body> tag.
  2. Confirm that the selected client token is active and that the Surface is Active.
  3. Confirm that the page origin is listed in Allowed Origins. Test tokens also allow local origins automatically.
  4. Check the browser console for errors.

API endpoint not found

An API request returns 404 when the endpoint URL points to a missing or inactive API Surface. The request also returns 404 when the URL uses the wrong Capability slug.

To fix the endpoint URL, follow these steps:

  1. Copy the endpoint URL from the API Surface’s Endpoints or Ship tab.
  2. Confirm that the URL uses the correct Product, Surface, and Capability values.
  3. Set the API Surface to Active and confirm that it has a linked, enabled Capability.

Inbound webhook rejected

When configured webhook verification fails, Runtype rejects the inbound delivery before it creates an execution. The rejection does not appear in Logs. The product editor marks a messaging channel with Rejecting events. It also shows a banner with the failure reason, guidance, and last rejection time.

Runtype returns 401 for invalid signatures or secrets on Slack, Telegram, Twilio, Sendblue, and Discord channel Surfaces. Email verification failures return 404 with Surface not found or inactive.

Check these causes:

  • The credential saved on the channel does not match the provider credential.
  • The provider URL points to a proxy or redirect, so the provider’s signature headers do not reach the Runtype endpoint.
  • The Surface was recreated, but the provider still sends events to the old webhook URL.

Use these provider-specific checks:

  • Slack: Copy the Signing Secret from Basic Information in your Slack app settings. Do not use the Client Secret. Confirm that Request URL points directly to the Runtype endpoint.
  • Telegram: Rerun the Telegram setup so the bot webhook and the Surface use the same secret token.
  • Twilio: Copy the Auth Token from the Twilio console for the account that owns the phone number.
  • Sendblue: Copy the signing secret from the Sendblue dashboard.
  • Discord: Copy the Public Key from General Information in the Discord developer portal. Confirm that Interactions Endpoint URL points directly to the Runtype endpoint.
  • Email: Add the webhook secret in the Surface’s Inbound settings. Send it in the X-Webhook-Secret header or as a Bearer token. For SendGrid Inbound Parse, add it to the forwarding URL as the webhook_secret query parameter. For Resend, use the signing secret from the Resend webhook.

To verify the fix, follow these steps:

  1. Open the Product’s Visual view.
  2. Click the channel marked Rejecting events.
  3. Open the Inbound tab and follow the banner guidance for the failed credential or URL.
  4. Save the corrected configuration and send a test message. The banner clears after a delivery succeeds.

For an error that creates an execution, inspect its message and stack trace in Logs. For a rejected inbound webhook, use the channel status and banner because the request does not create an execution.

Next steps

Use these guides to continue troubleshooting: