---
updatedAt: 2026-04-10T10:34:50.000Z
agentTools:
  projectIndex: https://developers.newo.ai/llms.txt
---

# Error codes and troubleshooting

This page covers common errors encountered during development and deployment on the Newo platform, along with their causes and resolutions.

***

## REST API error responses

The Newo REST APIs return errors in a standard JSON format:

```json
{
  "code": 400,
  "type": "validation_error",
  "reason": "Invalid request body",
  "errors": [
    {
      "field": "connector_idn",
      "message": "connector_idn is required"
    }
  ]
}
```

| **Field**  | **Description**                                                                  |
| :--------- | :------------------------------------------------------------------------------- |
| `code`     | HTTP status code                                                                 |
| `type`     | Error category                                                                   |
| `reason`   | Human-readable summary                                                           |
| `errors[]` | Array of field-level validation errors (present on `validation_error` responses) |

***

## HTTP status codes

| **Code** | **Meaning**           | **Common causes**                                                              |
| :------- | :-------------------- | :----------------------------------------------------------------------------- |
| `400`    | Bad Request           | Missing required fields, invalid parameter values, malformed JSON              |
| `401`    | Unauthorized          | Missing or invalid `x-portal-secret` header                                    |
| `403`    | Forbidden             | Valid credentials but insufficient permissions for the requested resource      |
| `404`    | Not Found             | Resource does not exist; check identifiers (customer IDN, attribute ID, etc.)  |
| `409`    | Conflict              | Duplicate resource — a connector or webhook with the same IDN already exists   |
| `422`    | Unprocessable Entity  | Request is syntactically valid but semantically invalid                        |
| `429`    | Too Many Requests     | Rate limit exceeded — back off and retry                                       |
| `500`    | Internal Server Error | Platform-side error — retry after a short delay; contact support if persistent |

***

## Skill script errors

### Action returns `null` unexpectedly

**Symptom:** A `{% set %}` variable is `null` when you expect a value.

**Common causes:**

* The attribute identifier is misspelled or does not exist for the account
* The persona has not yet had the attribute set
* The action was called outside the correct flow context (e.g., `GetUser()` in a timer skill where no user session is active)

**Resolution:** Log the return value with `{{SendMessage(text=Stringify(value))}}` in the Sandbox to inspect the actual output. Verify the attribute identifier using the Attribute Reference pages.

***

### `SendCommand()` fires but no response event arrives

**Symptom:** A `magic_http_response`, `magic_browser_response`, or `timer` event never arrives after calling `SendCommand()`.

**Common causes:**

* The `connectorIdn` in `SendCommand()` does not match the `connector_idn` in the event subscription
* The integration is not properly configured (missing API keys, invalid connector settings)
* The skill that calls `SendCommand()` exits before the response arrives (response events are asynchronous)

**Resolution:**

1. Check that `connectorIdn` in the `SendCommand()` call exactly matches `connector_idn` in the flow's event subscription.
2. Confirm the connector is properly configured in the Builder Integrations page.
3. Ensure the skill that calls `SendCommand()` does not block or return before the async response arrives — use a separate skill subscribed to the response event.

***

### `Gen()` / `GenStream()` produces unexpected output

**Symptom:** The LLM generates an incorrect, off-topic, or incomplete response.

**Diagnostic approach:** See **Debugging agent execution** in the Advanced Topics section. The core principle: if the output is wrong, something was missing from or incorrect in the prompt.

1. Find the broken reply in Sandbox logs.
2. Open the prompt sent to the LLM (visible in session logs).
3. Identify which information block was missing or incorrect.

***

### Variables from inside `{% if %}` or `{% for %}` are undefined outside the block

**Symptom:** A variable set inside a conditional block returns `undefined` when accessed later.

**Resolution:** In NSL, block scoping works differently from standard Jinja2 — variables set inside blocks **are** accessible outside. However, if a variable is only set in one branch of an `{% if %}`, it will be undefined if the other branch executes. Initialize variables with a default before the conditional:

```
{% set result = "" %}
{% if condition %}
  {% set result = "some value" %}
{% endif %}
{{ result }}
```

***

## Voice channel errors

### Calls drop immediately after answering

**Common causes:**

* STT provider is not configured or credentials are invalid
* The agent has no active flow or the `conversation_started` event has no subscription
* The Newo Voice connector is not properly provisioned

**Resolution:** Verify connector configuration in Builder. Check that the flow has an event subscription for `conversation_started` or `user_message` on the voice integration.

***

### Call transfer fails silently

**Common causes:**

* The `transfer_call_tool` is configured but the `escalation_phone` customer attribute is empty
* The destination number is formatted incorrectly (must include country code)

**Resolution:** Confirm `project_attributes_escalation_phone` is set for the account. Ensure the number is in E.164 format (`+15551234567`).

***

## Timer errors

### Timer fires but handler skill doesn't execute

**Common causes:**

* The `connectorIdn` used in `set_timer` does not match any event subscription's `connector_idn`
* The flow containing the timer subscription is not the active flow for the persona

**Resolution:** Cross-check the `connectorIdn` value in the `SendCommand()` call against the `connector_idn` in the event subscription in the flow YAML.

***

## Webhook errors

### Outgoing webhook returns `400` from the target server

**Common causes:**

* Payload format does not match what the target server expects
* Missing or invalid authentication headers

**Resolution:** Inspect the webhook payload using the session logs. Confirm the target server's expected content type and authorization mechanism.

### Incoming webhook payload is not processed

**Common causes:**

* The incoming webhook URL is not registered or is misconfigured
* The `command_idn` in the payload does not match a registered command

**Resolution:** Verify the webhook is registered via the Webhooks API. Check that the payload's `command_idn` matches a command registered in your flow.

***

## Getting help

If you cannot resolve an issue using this guide:

1. Review Builder session logs — they contain full prompt content, event traces, and skill execution history.
2. Contact <support@newo.ai> with your customer IDN, a description of the issue, and relevant session log excerpts.