> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.
# Actions troubleshooting
> Fix common AI Actions failures — OpenAPI import errors, 401s that pass in Test, production calls that never land, and AI skipping an action.
Before debugging, have these ready: the **action name**, a **session ID** where it should have been called, and the **endpoint** you expect to receive traffic.
Looking for setup? See [Build an action](/actions/build-an-action). For the runtime model, see [Execution](/actions/execution).
## Common Troubleshooting Scenarios
| Symptom | Likely cause | What to do |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAPI import fails with `invalid_tool_schema`** | One operation uses schema features the AI tool validator rejects — nested `oneOf`, circular `$ref`, non-JSON-Schema types | Simplify the offending operation, flatten `oneOf`, resolve circular refs, re-upload. See [OpenAPI import](/actions/openapi-import). |
| **Endpoint returns 401 / 403 but Test works** | The **Test** call injects placeholder `x-opencx-*` context headers; your production middleware blocks them, or your bearer-token casing differs between the Test payload and the saved [global variable](/actions/authentication) | Allow `x-opencx-*` through your WAF. Confirm the global variable value matches the **full** `Authorization` string, including any `Bearer ` prefix. |
| **Test passes but the production call never lands** | CORS (widget path only), firewall / IP allowlist, or provider-side rate limit on your production endpoint | Add OpenCX egress IPs to your allowlist — ask support for the current list. Check CORS for widget-initiated calls. Inspect your API gateway for rate-limit denials. |
| **AI doesn't call the action at all** | Channel toggle off, segment restriction excludes this contact, or the description is too vague for the AI to match intent | Enable the channel on the action's page. Verify the contact's [segment memberships](https://platform.open.cx/contacts). Sharpen the description to name the noun + verb (e.g. *"look up an order by ID and return tracking details"*). |
| **None of the above** | — | Capture the session ID and action name, contact support. |
OpenCX enforces a **60-second timeout** and **does not retry**. Failures return to the AI as status codes or a short error string — see [Execution](/actions/execution) for the exact failure shapes.
## Limits Recap
| | Value |
| --------------------- | --------------------------------------- |
| **Request timeout** | 60 seconds (no retries) |
| **Transport** | HTTPS only |
| **Supported methods** | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
| **Body formats** | JSON, `multipart/form-data` |
## Impact Of Misconfiguration
Misconfigured actions fail silently from the customer's point of view — the AI either calls the wrong endpoint, gets an error and covers with a generic fallback, or skips the action entirely and hands off. None of these show up as a red banner in the dashboard. **Always verify in a real conversation after changing an action's endpoint, description, or segment restriction.**
***
## Related Documentation
Re-check fields, magic values, and the Test button.
Re-check timeout, headers, and response handling.
Global variables, widget headers, context headers.
What happens when repeated action failures escalate.