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

# Troubleshooting Common Scalysis API Errors and Fixes

> Diagnose and resolve the most common errors you may encounter while integrating with the Scalysis AI-powered calling API, with step-by-step fixes.

When something goes wrong with a Scalysis API call, the response will almost always include a descriptive error message to point you in the right direction. This page walks you through every common error, explains why it happens, and shows you exactly what to change so you can get back to making calls as quickly as possible.

## Common Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **What it means:** The server could not verify your identity. Your API key is either missing from the request, misspelled, or formatted incorrectly.

    **How to fix it:**

    Make sure every request includes one of the two accepted auth headers. Choose whichever style your HTTP client makes easiest:

    ```http theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    ```http theme={null}
    X-API-Key: YOUR_API_KEY
    ```

    <Warning>
      Do not include both headers in the same request — use one or the other. Also confirm you are copying the full key from the Scalysis dashboard with no leading or trailing spaces.
    </Warning>

    For `POST` requests, you also need the content-type header alongside your auth header:

    ```http theme={null}
    Content-Type: application/json
    ```
  </Accordion>

  <Accordion title="400 scriptId is required">
    **What it means:** You sent a trigger or campaign-creation request without a `scriptId`, or the value you provided is not a valid number.

    **How to fix it:**

    Include `scriptId` in your request body and make sure its value is the **integer** shown in the Scalysis UI for the AI agent script you want to use — not a string.

    ```json theme={null}
    {
      "scriptId": 42,
      "customerPhone": "+12025550147"
    }
    ```

    <Note>
      You can find your script IDs by logging into the Scalysis dashboard and navigating to the **Scripts** section. Each script card displays its ID.
    </Note>
  </Accordion>

  <Accordion title="400 customerPhone is required">
    **What it means:** The phone number to dial is missing. This can happen either because you omitted `customerPhone` from the trigger body, or because a contact in your campaign's `contacts[]` array is missing a phone field.

    **How to fix it:**

    For a single-call trigger, add `customerPhone` directly to the request body:

    ```json theme={null}
    {
      "scriptId": 42,
      "customerPhone": "+12025550147"
    }
    ```

    For a campaign using `contacts[]`, make sure every contact object includes a phone number:

    ```json theme={null}
    {
      "contacts": [
        { "phone_number": "+12025550147", "name": "Alex Johnson" },
        { "phone_number": "+13105550198", "name": "Sam Rivera" }
      ]
    }
    ```

    If you are using `csvText` instead, verify the column specified by `phoneColumn` (default: `"phone_number"`) is present and populated in every row.
  </Accordion>

  <Accordion title="400 Missing required script variables: brand_name">
    **What it means:** The script you selected contains a `brand_name` placeholder, but you did not supply a value for it in the request body. The AI agent cannot speak the brand name during the call without it.

    **How to fix it:**

    Add `brand_name` as a top-level field in your request body:

    ```json theme={null}
    {
      "scriptId": 42,
      "customerPhone": "+12025550147",
      "brand_name": "Acme Store"
    }
    ```

    <Tip>
      If your script uses other custom variables beyond `brand_name`, the error message will list all of the missing ones at once (e.g., `Missing required script variables: brand_name, agent_name`). Add each missing variable as its own key in the request body.
    </Tip>
  </Accordion>

  <Accordion title="404 Call is still in progress">
    **What it means:** You sent a `GET` request for a call outcome, but the call has not finished yet. Scalysis returns a `404` here to signal that a finalized result does not exist yet — not that the `order_id` is wrong.

    **How to fix it:**

    Wait **10–30 seconds** after triggering a call before polling for the outcome, then retry your `GET` request:

    ```http theme={null}
    GET /api/order/{order_id}/call-outcome
    ```

    <Note>
      Build a short retry loop into your integration rather than firing the outcome request immediately after the trigger response. A simple approach is to wait 15 seconds, then poll every 5 seconds until you receive a successful response.
    </Note>
  </Accordion>

  <Accordion title="404 Order not found / Campaign not found">
    **What it means:** The `order_id` or `campaign_id` you referenced does not exist under the API key you are using. This usually means one of the following:

    * You used an ID from a different store or a different API key.
    * You mistyped or truncated the numeric ID.
    * The resource was deleted from the Scalysis dashboard.

    **How to fix it:**

    Double-check that the `order_id` or `campaign_id` value matches exactly what was returned in the original trigger or create response:

    ```json theme={null}
    {
      "success": true,
      "order_id": 8471
    }
    ```

    <Warning>
      IDs are scoped to your API key. An `order_id` created with one key is not accessible using a different key, even within the same Scalysis account.
    </Warning>
  </Accordion>

  <Accordion title="400 Concurrency / Pool Exhausted">
    **What it means:** Your account's calling channel pool is fully occupied by active campaigns. Scalysis cannot start new concurrent calls until capacity is freed up.

    **How to fix it:**

    You have two options:

    1. **Pause or stop a running campaign** to release channels, then start the new one.
    2. **Lower `maxConcurrency`** on your active campaigns so they each consume fewer channels, leaving room for the new one.

    ```json theme={null}
    {
      "action": "pause",
      "campaign_id": 1023
    }
    ```

    <Info>
      The server may also enforce a hard cap on `maxConcurrency` regardless of what you request. If you need a higher concurrency limit, contact Scalysis support to discuss your plan limits.
    </Info>
  </Accordion>
</AccordionGroup>

***

## Auth Header Reference

Every request to the Scalysis API must be authenticated. You can use either of the two header formats below — pick one and use it consistently across all your requests.

**Option A — Bearer token:**

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

**Option B — X-API-Key:**

```http theme={null}
X-API-Key: YOUR_API_KEY
```

For any `POST` request (triggering a call, creating a campaign, controlling a campaign), include the content-type header as well:

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

Here is a complete `POST` example using `curl`:

```bash theme={null}
curl -X POST https://app.scalysis.com/api/trigger-call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scriptId": 42,
    "customerPhone": "+12025550147",
    "brand_name": "Acme Store"
  }'
```

And a `GET` example for fetching a call outcome:

```bash theme={null}
curl https://app.scalysis.com/api/order/8471/call-outcome \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Tip>
  Every successful Scalysis response includes `"success": true` at the top level. Make this the first field you check in your integration logic — if it is absent or `false`, read the accompanying `message` field for a plain-English description of what went wrong.
</Tip>