Common errors and solutions | Runtype Documentation

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

Authentication errors

Runtype returns these errors before it runs your request. For sign-in and organization problems in the dashboard, see Authentication issues.

Invalid API key

An invalid or missing credential produces a 401 Unauthorized response. An API Surface returns Invalid API key for a key that does not match an active key on that Surface. An expired Surface key returns API key has expired, and a Surface that is not Active returns API surface is not active.

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:

Confirm that the request sends the key in the Authorization header as a Bearer token.
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.
For an API Surface, open Keys and use a papi_ key issued by that Surface. Every Surface accepts both Test and Production keys.
If a management key is expired or exposed, regenerate it in Settings > API.
If a Surface key is expired or exposed, create a replacement key in the Surface’s Keys tab.

An API Surface also accepts the key in the X-API-Key header.

Insufficient permissions

A valid key that lacks access returns 403 Forbidden. The response names what the key is missing:

Insufficient permissions. Required: FLOWS:READ or another permission: the management key does not have the permission that the endpoint requires. In Settings > API, edit the key and add the named permission.
API key does not have access to capability '...': the API Surface key is scoped to other Capabilities. Add the Capability to the key’s scope. For the steps, see Scoping API keys to Capabilities.

Origin not allowed

The chat API returns 403 with Origin not allowed when the page origin is missing from the client token’s allowed origins or from the chat Surface’s Allowed Origins. Runtype checks both lists, and the origin must pass both.

To fix an origin error, follow these steps:

Open the Product that contains the chat Surface.
On the Surface panel, click Auth.
Add the full page origin to Allowed Origins, including its scheme, hostname, and port when required.
Confirm that the client token’s allowed origins also include the page origin.
Confirm that the Surface is Active.
Confirm that the Surface has at least one enabled Capability.

For other chat widget errors, such as Session not found or expired, see Client tokens and domain restrictions.

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:

Open Logs and inspect the slow step’s duration and timeout value.
Reduce the work that the step performs.
If the work needs more time, raise options.stepTimeoutMs or options.flowTimeoutMs on the request. An attached request allows up to 10 minutes per step and 15 minutes per Flow.

For every entry point and its maximum values, see Timeouts and long-running work.

Undefined variable

When a step references a variable that no earlier step sets, Runtype leaves the {{name}} text unchanged, so a prompt receives the literal placeholder. In a transform-data or code step, reading a property of the missing value fails with an error similar to Cannot read properties of undefined (reading 'output').

The Flow validator reports this mistake before you run the Flow. It returns the UNDECLARED_VARIABLE_REFERENCE warning, which is similar to the following: Variable "{{summary}}" is referenced but no earlier step declares an output variable "summary". The warning details also list the variables that are available at that step.

Use these checks to resolve the error:

Confirm that the reference matches the earlier step’s outputVariable spelling. Compare it with the available variables in the warning.
Confirm that the referenced step runs on the selected conditional branch before the later reference.
If the value comes from the caller, declare the variable as a Flow input.
If the variable can be missing, supply a fallback with ??, either in the template, such as {{summary ?? 'none'}}, or in JavaScript code.

Rate limit exceeded

Runtype returns 429 when you start executions faster than your plan’s burst rate allows. The burst rate is the number of executions that you can start in a 10-second window. The Retry-After header tells you when to retry.

To handle a burst-rate 429, follow these steps:

Read the Retry-After header from the response.
Retry the request after the specified interval.
For large workloads, space out execution requests in your client, or run the work as a batch or Schedule with lower concurrency.

The following limits also return 429:

An API Surface key or webhook Surface credential over its per-minute or per-day limit returns Rate limit exceeded with the code RATE_LIMITED. Raise the key’s limits, or wait for Retry-After. For more information, see Calling your API endpoints.
A test key over its daily or lifetime execution limit returns TEST_KEY_DAILY_LIMIT_EXCEEDED or TEST_KEY_LIFETIME_LIMIT_EXCEEDED. A lifetime limit does not reset. Use a live management key or a Production Surface key instead.
An eval run over your daily eval limit returns the code DAILY_EVAL_LIMIT or DAILY_EVAL_LIMIT_EXCEEDED. The limit resets at midnight UTC.

AI model providers apply separate limits to model requests. If platform-key throughput limits your requests, use your own provider key.

Spend limit reached

Runtype returns 402 when a spending control blocks your request. A retry fails until you change your billing settings or the limit resets. The response code names the cause:

SPEND_LIMIT_EXCEEDED: your month-to-date spend reached your monthly spend cap. The cap resets at the start of each month (UTC), and resetsAt in the response gives that time. To resume sooner, raise or clear the cap in Settings > Billing.
PLATFORM_KEY_SPEND_EXCEEDED: platform-key credit is unavailable. To resume, set a default payment method in Settings > Billing, or use your own provider keys.

For the difference between 429 and 402 responses, see Rate limits and usage.

Flow validation errors

The Flow validator checks a Flow before it runs. It rejects errors and reports warnings for configurations that fail at runtime.

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:

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

Unquoted placeholder in a condition

A condition or when expression runs as JavaScript after Runtype substitutes the placeholders. When status is healthy, the unquoted placeholder in {{status}} === 'healthy' becomes healthy === 'healthy', and the run fails with ReferenceError: healthy is not defined. The validator reports this problem as CONDITION_UNQUOTED_TEMPLATE_COMPARISON.

To fix the expression, put quotes around the placeholder: '{{status}}' === 'healthy'.

Record source is not JSON

An upsert-record step needs a JSON object as its source. When the source variable comes from a prompt step that returns text, the validator reports UPSERT_RECORD_SOURCE_NOT_JSON, and the step fails at runtime.

To fix the source, use one of these approaches:

Set the prompt step’s responseFormat to json.
Add a transform-data step that wraps the text in an object.
Set contentField on the upsert-record step to wrap the text automatically.

Malformed variable reference

The validator reports MALFORMED_VARIABLE_REFERENCE when a field contains {summary} instead of {{summary}}. Runtype substitutes only double-brace references, so the single-brace text reaches the step unchanged. To fix the reference, use double braces.

Integration errors

These errors come from Tools and the external services that they call.

Secret not configured

A Tool, custom MCP server, or template that references {{secret:NAME}} fails when that secret does not exist. The error is similar to the following: Tool "lookup-order" requires secrets that are not configured: ORDER_API_KEY. Please add these secrets in Settings > Secrets. A custom MCP server also fails when the secret has an empty value.

To fix the error, follow these steps:

Open Settings > Secrets.
Create the secret with the exact name from the error message and a non-empty value.
Run the Flow or Agent again.

For more information, see Managing secrets.

Slack message failed

If an Agent’s Slack tool cannot send a message, check the Slack workspace installation, target channel, and Agent tool configuration.

Use these checks:

Confirm that a Slack workspace is installed in your Runtype organization. The Slack tools use the workspace that a Slack Surface installs. For the steps, see Setting up a Slack Surface.
Confirm that the bot is a member of the channel and can post to it.
Confirm that the Agent includes the Slack tool that sends messages.

The Bot Token form that opens when you select Slack in an Agent’s tools returns an error and does not save Slack credentials. Install the workspace through a Slack Surface instead.

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

These errors occur when a step selects a model that is not configured or when the provider rejects the request.

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:

Open Settings > Models and check the Models tab.
If the model is not listed, click Add model and add it.
If the model uses your own provider key, open the Providers tab and verify the key.
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.

To find models that support larger inputs, open Settings > Models, click Add model, and use the Context Length filter.

Surface errors

These errors occur when a chat widget, API Surface, or messaging channel cannot reach your Product.

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:

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

API endpoint not found

An API request returns 404 when the endpoint URL points to a missing API Surface or uses the wrong Capability slug. A request to a Surface that is not Active can return 404 or 401, depending on the endpoint.

To fix the endpoint URL, follow these steps:

Copy the endpoint URL from the API Surface’s Endpoints or Ship tab.
Confirm that the URL uses the correct Product, Surface, and Capability values.
Set the API Surface to Active.
Confirm that the Surface 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.

An Email Surface that uses Resend can also show Rejecting events after verification succeeds, when Runtype can’t fetch the email content from Resend or queue the message. A permanent failure, such as an invalid API key, a key without the Receive emails permission, or an email that Resend can’t find, is acknowledged with 200 and recorded in the banner. A temporary Resend or queue failure returns 503, so Resend delivers the email again.