Core

Errors

View as MarkdownOpen in Claude

Reference for the error codes that SWML reports when a document fails to fetch, parse, or run. Calling and messaging SWML use different code namespaces:

  • Calling errors start with relay_script_* and surface on the call session as the script_error variable and as calling.script.warning events.
  • Messaging errors include the swml_* codes for messaging-specific failures plus a handful of document-level codes. They appear on the inbound message in the Messaging logs and on any status callbacks you’ve configured.

Calling errors

Errors raised while executing a calling SWML document. Each error is reported with a contextual message describing the offending method, parameter, or condition. You can read the code from the script_error variable on the call session or from the payload of the calling.script.warning event.

relay_script_parse_error
string

The fetched document could not be parsed as valid JSON or YAML, or the dest URL of a transfer was malformed.

relay_script_parse_internal_error
string

An internal parsing error occurred while reading the document. Verify the document is valid YAML or JSON and retry.

relay_script_version_invalid
string

The document’s version value is not a supported SWML version.

relay_script_sections_missing
string

The document has no sections element.

relay_script_main_section_missing
string

The document’s sections is missing the required main section.

relay_script_section_code_missing
string

A section is defined but contains no executable steps.

relay_script_section_parameter_undefined
string

An execute step references a section that does not exist in the document.

relay_script_element_undefined
string

An unrecognized top-level element appears in the document.

relay_script_element_wrong_type
string

A document element has the wrong JSON type for its position (for example, an array where an object was expected).

relay_script_element_invalid_value
string

A document element has an invalid value (for example, an enum-valued field set to an unrecognized string).

relay_script_element_duplicated
string

A document element that may appear at most once was provided multiple times.

relay_script_method_missing_name
string

A step in a section does not have a method name (the step entry is malformed).

relay_script_method_undefined
string

A step references a method that is not a recognized SWML calling method.

relay_script_method_parameter_missing
string

A required parameter for the method is missing — for example, transfer without dest, or request without url.

relay_script_method_parameter_invalid_value
string

A method parameter has an invalid value — for example, a request.method that is not one of the supported HTTP verbs, or a switch.variable that does not resolve to a valid variable name.

relay_script_method_parameter_undefined
string

A method received a parameter name it does not recognize.

relay_script_method_parameter_conflict
string

Two mutually-exclusive parameters were provided on the same method.

relay_script_method_no_matching_condition
string

A switch step matched no case and no default was provided.

relay_script_method_execute_failed
string

A method failed while running — for example, a media playback failure, a transfer that couldn’t dial, or a tap or stream that couldn’t be set up. The accompanying message provides the specific cause.

relay_script_js_eval_error
string

A JavaScript expression in a cond, switch, eval, or when clause raised an error.

relay_script_nested_too_deep
string

A document or one of its sections is nested beyond the maximum depth.

relay_script_too_many_transfers
string

The chain of transfer and goto steps exceeded the platform maximum (32 transfers per call).

relay_script_internal_error
string

An internal server error occurred during script execution.

Messaging errors

Errors emitted when an inbound message’s SWML document fails to fetch, parse, or execute. Each inbound message is marked failed with the listed error_code and a corresponding error_message, visible in the Messaging logs.

Document fetch / route

unrouteable_message
string

Unrouteable message received — no SWML handler is assigned to the inbound number.

insufficient_balance
string

Insufficient account balance to receive the message.

message_filtered
string

Message filtered (e.g. spam detection or carrier-level filtering).

http_retrieval_error
string

The attempt to retrieve the SWML document timed out or failed.

url_failed_to_parse
string

The configured SWML URL could not be parsed.

Document parse

json_or_yaml_required
string

The document must be valid JSON or YAML.

swml_invalid_document
string

Document may contain only one of reply, receive, or sections at the top level.

swml_missing_entry_point
string

Document must contain reply, receive, or sections.

swml_invalid_section_format
string

Section main must be an array of steps.

swml_unsupported_method
string

The document references an unsupported SWML messaging method.

reply method

swml_reply_failed
string

Failed to create the reply message (general fallback for reply persistence errors).

swml_reply_media_limit_exceeded
string

The reply exceeds the maximum of 8 media attachments.

swml_reply_body_or_media_required
string

The reply must include a body or media.

swml_reply_invalid_from_number
string

The reply from number is not a valid PhoneRoute or ShortCode in this project.

swml_reply_invalid_to_number
string

The reply to number has an invalid format.

swml_reply_missing_messaging_capability
string

The reply from number is not SMS- or MMS-capable for the kind of message being sent.

swml_reply_character_limit_exceeded
string

The reply body exceeds the character limit for the destination.

swml_reply_inactive_campaign
string

The reply from number must belong to an active 10DLC campaign.

switch method

swml_switch_no_match
string

switch matched no case and no default was provided.

swml_switch_invalid_transform
string

switch.transform is not one of lowercase, uppercase, trim, lowercase_trim, uppercase_trim.

execute method

swml_section_not_found
string

The section named by execute.dest is not defined in the current document.

transfer method

swml_transfer_failed
string

transfer.dest is required and was missing or empty.

swml_transfer_fetch_failed
string

Failed to fetch the transferred SWML document from the destination URL.

swml_transfer_document_invalid
string

The transferred SWML document is not a valid messaging document.

goto method

swml_goto_label_not_found
string

goto.label does not match any label step in the current section.

request method

swml_request_url_required
string

request.url is required and was missing or empty.