Phone system

Troubleshooting

Start from the symptom you see. Sailor returns machine-readable error strings so your backend can log the exact failure and choose the next action.

Pick the card that matches the failure mode, then work through the checks in that section.

Start Here

Request was rejected

The API returned unauthorized, forbidden, or feature_disabled.

Outcome did not save

Create or update returned invalid_outcome or destination_not_found.

Webhook did not arrive

An action outcome was applied, but your endpoint did not receive a payload.

Post-call workflow did not appear

Agents are not seeing a required disposition step after calls.

Request Was Rejected

ErrorMeaningFix
unauthorizedThe request could not be authenticated.Check the Authorization header and token value.
forbiddenThe token is valid, but not allowed to perform this action.Use a token with permission to manage phone-system outcomes.
feature_disabledPhone-system outcomes are not enabled for the workspace.Enable the phone-system feature before calling the endpoint.
no_subaccountSailor could not resolve the workspace scope.Confirm the token is attached to the expected workspace.

Outcome Did Not Save

ErrorLikely causeFix
missing_idempotency_keyA create or update request omitted Idempotency-Key.Add a stable key for the logical operation.
idempotency_key_in_useThe same idempotency key is already being processed.Wait for the first request to finish, then retry with the same key if it was the same operation.
invalid_outcomeThe request body failed validation.Check outcome type, destination fields, and webhook URL rules.
destination_not_foundThe target Smart List does not exist in the workspace.Use a Smart List ID from the same workspace as the token.
outcome_not_foundThe requested outcome ID does not exist.List outcomes and retry with an ID returned by Sailor.

Webhook Did Not Arrive

Check these in order:

1

Confirm the outcome is an action

Webhooks are sent for action outcomes with a configured webhook_url.

2

Confirm the URL is public HTTPS

Localhost and private network URLs cannot receive Sailor webhooks. Use a tunnel for local testing.

3

Confirm your server returns 2xx

Return a 2xx status after accepting the payload. Move slow work into a queue.

4

Check your receiver logs

Log request method, path, status, and body while testing.

Post-Call Workflow Did Not Appear

disposition_popup_enabled is true only when at least one outcome has outcome_type: "disposition".

If agents do not see a post-call disposition step:

  1. Call GET /phone-system/outcomes.
  2. Confirm at least one returned outcome has outcome_type: "disposition".
  3. Confirm the agent is using the same workspace as the API token.
  4. Create a disposition outcome if none exists.

Smart List Movement Did Not Match Expectation

What happenedWhat to check
Person was not added to a list.The outcome should use destination_type: "smart_list" and a valid destination_id.
Person was not removed from lists.The outcome should use destination_type: "remove_from_smart_list" and remove_from_smart_lists.
Only some lists changed.For selected removal, confirm every list ID is present in remove_from_smart_lists.list_ids.

Still Stuck

Capture the method, path, request body, response body, and approximate time of the request. If the issue involves a webhook, include your receiver logs and the outcome ID.