[DOC] - Add New Codes/Mappings to SW REST API Errors #703
Description
Describe the requested update
I have attached a full list of all the error code/mapping pairs returned by the SignalWire REST APIs.
Variables wrapped in %{} are placeholders where the inserted values may vary due to us using the code across multiple endpoints.
I'll cover invalid_parameter outside of the main list, because it's a special case associated with a variety of standard validation errors. These are generally accompanied with messages that are relatively descriptive already.
I added several examples to show the variety, but this may not be the full scope. I'm not sure how we want to represent this to the customer as it is by no means a static list. If they receive an error response with the code invalid_parameter and the error message feels unclear, I'd advise them to open a ticket so that we can improve the messaging in that case or implement a more custom code.
| Validator | Message |
|---|---|
greater_than |
must be greater than %{count} |
equal_to |
must be equal to %{count} |
less_than |
must be less than %{count} |
greater_than_or_equal_to |
must be greater than or equal to %{count} |
less_than_or_equal_to |
must be less than or equal to %{count} |
other_than |
must be other than %{count} |
too_short |
is too short (minimum is %{count} characters) |
too_long |
is too long (maximum is %{count} characters) |
wrong_length |
is the wrong length (should be %{count} characters) |
acceptance |
must be accepted |
presence |
can't be blank |
absence |
must be blank |
value_not_unique: The passed value must be unique, but it is not.
missing_required_parameter: The passed value is blank or empty, but it is required.
account_limit_exceeded: The account must be upgraded to perform this action
address_has_no_valid_channels: The address has no valid channels.
allowed_address_limit_exceeded: maximum number of allowed addresses is %{allowed_address_limit}
already_assigned: is already assigned to %{target}
already_verified: is already verified
authblock_is_expired: The expires_at timestamp of the subscriber from the authblock has passed.
authblock_is_invalid:The authblock is invalid or doesn't reference an existing subscriber.
auto_top_up_deactivated: Auto top-up is not active on this account
billing_route_not_found: Unable to locate a billing route.
brand_not_unique: CSP Brand Reference must be unique within space.
call_id_is_duplicated: The provided call ID is already associated with an existing call.
campaign_inactive: Numbers cannot be assigned to an inactive campaign
campaign_not_active: Campaign must be active
cannot_cancel_in_progress: Cannot cancel an in-progress call.
cannot_process: cannot process the request right now
cannot_redirect_not_in_progress: Call is not in-progress. Cannot redirect.
cannot_remove_assignment_from_integration_test: Cannot remove assignment from an integration test campaign
incompatible_parameters: The parameters %{parameters} cannot be specified together"
cannot_update_completed: Cannot update a completed call.
channel_has_missing_properties: Channel must have read or write property.
channel_name_is_reserved: The channel name may not begin with %{prefix}.
channel_name_size_limit_exceeded: Channel name can not exceed %{limit}
channel_size_limit_exceeded: The number of channels must be less than %{limit}.
chat_token_invalid_for_session: The provided token is invalid for the provided room session.
chat_token_is_invalid: The provided token is not a valid chat token.
contains_external_entities: XML contains external entity definitions which are not allowed for security reasons.
conversation_flow_steps_are_invalid: must be an array. Example: [\"Intro\", [\"Introduce yourself\", \"Ask caller's name\"], \"Summarize the conversation and thank the caller\"]
could_not_purchase: could not be purchased
document_version_mismatch: The document_version does not match the current record's document_version.
does_not_exist: does not exist
domain_has_no_password: The domain has not been configured with a password.
duplicate_skill_type: Only one %{skill} skill can exist per AI Agent
exceeds_history_logs_limit: The value exceeds the %{date_range} date limit.
no_installed_applications: Fabric Application must be installed in this project
feature_not_available: This feature is not available to this account
file_already_exists: An asset already exists with this project, path, and filename.
file_can_not_be_opened: An error occurred trying to open the provided file.
file_exceeds_size_limit: File is too large. Maximum allowed size is %{size} %{unit}.
file_not_found: The requested file could not be found (404 Not Found). Please check the URL and try again.
from_fabric_address_id_does_not_match_subscriber: The provided from_fabric_address_id does not match an address for the provided subscriber.
incorrect_keyword_format: "Keywords must be comma separated values with no space."
incorrect_number_of_sub_use_cases_low_volume: "Mixed use case campaigns require minimum 2 and maximum 5 sub use cases."
incorrect_number_of_sub_use_cases_mixed: "Mixed use case campaigns require minimum 2 and maximum 5 sub use cases."
inline_swml_or_swml_webhook_required: "You must pass instructions through inline SWML or a URL to a SWML document."
insufficient_balance: "The account has insufficient balance"
invalid_addresses_for_transfer_skill: "Addresses must contain non-empty values for name and destination"
invalid_auth_token_permissions: "contains invalid selections (valid permissions are: %{valid_scopes})"
invalid_call_handler_for_external_swml_handler: "must be calling or messaging"
invalid_call_handler_for_swml_application: "must be external_url or script"
invalid_call_id_passed: "The call ID must not point to a cXML call."
invalid_command_attempted: "The specified command is invalid."
invalid_content_type: "Invalid content type. Allowed content types are: %{allowed_types}"
invalid_for_page_chunking: "chunking params are not allowed for page chunking"
invalid_for_paragraph_chunking: "chunking params are not allowed for paragraph chunking"
invalid_for_sentence_chunking: "provided chunking params are not valid for sentence chunking. Allowed params are max_sentences_per_chunk and split_newlines"
invalid_for_sliding_chunking: "provided chunking params are not valid for sliding chunking. Allowed params are chunk_size and overlap_size"
invalid_for_type: "is not valid for %{type}"
invalid_group_configuration: "Fabric addresses must form a valid conversation group (a single room or two non-room subscribers) and group ID must start with 'sw_'"
invalid_handler_use: "must be calling or messaging"
invalid_http_method: "must be GET or POST"
invalid_join_until_date: "Join Until date can't be in the past of Join From date"
invalid_list_items: "The items %{items} are invalid - %{details}"
invalid_mustache_syntax: "invalid mustache syntax."
invalid_object: "%{error_message}"
invalid_pstn_destination: "The PSTN destination is either missing or not in E164 format."
invalid_relay_connector_parameters: "Send relay_connector_id to link to an existing connector or relay_connector_name and relay_connector_token to create a new one."
invalid_resource_for_handler: "is not valid for a %{handler} handler"
invalid_resource_type: "%{resource_type} is not a valid resource type"
invalid_sip_configuration: "The %{value} passed is invalid. Allowed values are: %{allowed_values}"
invalid_sip_destination: "The SIP destination is either missing or could not be parsed."
invalid_state: "The object is not in the correct state for this action"
invalid_sub_use_cases: "%{use_case} is not a valid sub use case."
invalid_subproject_id: "must be id of subproject belonging to project used to authenticate request"
invalid_token_format: "The format of the provided token is invalid"
invalid_zendesk_capability: "Invalid Zendesk Capability"
list_contains_invalid_entries: "contains an invalid entry"
malformed_xml: "XML is not well formed"
max_queued_calls_exceeded: "has exceeded the maximum number of queued calls"
max_queued_messages_exceeded: "has exceeded the maximum number of queued messages for this number"
messaging_provider_invalid: "Messaging provider is invalid"
missing_sip_configuration: "The SIP configuration requires a selection of at least one %{value}"
missing_sub_use_cases: "Sub use cases are required for MIXED and LOW_VOLUME_MIXED campaigns."
must_belong_to_project: "The %{entity} must belong to the project"
must_specify_related_parameter: "must be used in combination with %{related_parameter}"
no_channel_specified: "must specify a channel"
no_devices_or_registrations: "The fabric address has no registered devices or current online registrations."
no_fabric_addresses: "The resource has no fabric addresses."
no_registered_devices: "The fabric address has no registered devices."
no_steered_resource: "Project has steering tag %{steering_tag} set, but there is no steered resource for that tag available"
no_valid_number_for_random_send_as_selection: "There is no purchased or verified number in the project to select as the send_as."
not_a_boolean: "must be true or false"
not_a_datetime: "must be a datetime"
not_a_hash: "must be a valid hash"
not_a_refresh_token: "invalid token type. You must use a Refresh token."
not_a_string: "must be formatted as a string"
not_a_valid_json: "must be valid JSON"
not_allowed_on_subscription_plan: "This feature is not allowed on the %{tier} subscription plan."
not_alphanumeric: "must be alphanumeric"
not_an_array_of_hashes: "must be an array of hashes"
not_an_array_of_strings: "must be an array of strings"
not_an_http_url: "must be an HTTP or HTTPS URL"
not_available_for_assignment: "is not available for assignment to %{target}"
not_e164: "is not a phone number in E.164 format"
not_json_or_yaml: "must be a valid JSON or YAML document"
not_parsable: "is not parsable"
not_parseable: "is not parseable"
not_purchased_or_verified: "must be a purchased or verified phone number"
not_registered: "The endpoint is not registered."
not_routable: "Unable to locate a route to the destination number. Please check geographic permissions and the destination number, and contact Support if issues persist."
not_valid_for_caller_id: "is not valid (must be an E.164 number, caller ID string or SIP URI)"
not_voice_capable: "must be a voice capable phone number"
number_assignment_cannot_be_removed: "Number assignments can only be removed if they are active, failed, or assigned to a pending campaign."
number_of_assignments_exceed_limit: "The requested assignment would exceed the allowed total of numbers (%{max_number_assignments}) that can be assigned to the selected campaign."
out_of_sync: "is out of sync"
page_token_is_invalid: "The provided page token is not valid."
page_token_required: "is required if your page_number value is larger than 0."
page_token_required_for_next_page: "The page token is required when the page number is passed and greater than 0."
provided_id_is_unrecognized: "The provided ID is unrecognized. Verify that the ID points to a valid resource belonging to the current project."
purchased_too_recently: "was purchased too recently to release. Please wait until %{release_date} to release this number, or contact Support for assistance."
query_processing_failed: "Can't process the query at the moment. Please try again later."
resource_assigned_as_handler: "cannot delete a resource currently assigned as a call or message handler"
resource_in_different_project: "The fabric resource is in a different project."
resource_not_allowed: "Calls to this fabric resource are not allowed with this authorization."
resource_not_callable: "The fabric resource is not callable."
resource_not_deletable: "Resource cannot be deleted"
room_is_not_chat_enabled: "The room for the provided room session does not have chat enabled."
invalid_room_session: "The room session ID does not point to a valid room session."
room_token_invalid_for_session: "The provided token is invalid for the provided room session."
room_token_is_invalid: "The provided token is not a valid room token."
sat_must_have_application: "Signalwire Access Token must be associated with a Fabric Application to perform this action"
send_as_is_invalid: "The provided send_as number is missing or invalid."
sip_gateway_uri_must_be_external: "Only external SIP entities are supported for the SIP Gateway. Do not provide a SignalWire-managed SIP entity."
sort_order_validations: "can't be specified without sort_by"
state_size_limit_exceeded: "State size can not exceed %{limit}"
sub_use_cases_present: "Sub use cases are not permitted for non mixed campaign use case."
terms_and_conditions_required: "You must agree to the terms and conditions to complete registration."
to_destination_unresolvable: "To does not resolve to a valid destination."
token_expired: "Token has expired."
token_has_invalid_prefix: "The token includes an invalid format prefix."
token_invalid: "The provided token is invalid."
token_invalid_or_unadoptable: "is incorrect or not ready for adoption"
token_not_associated_with_video_room: "The provided token is not associated with a valid video room."
too_many_verification_attempts: "has had too many incorrect attempts to verify this number"
too_many_verification_requests: "has had too many call requests without verifying this number"
too_many_verification_requests_in_time_frame: "This account has had too many Verified Caller ID requests within a short timeframe. As a precaution, we have disabled creating more for a short time. Please contact support if you need this restriction lifted sooner"
not_unique_within_project: "must be unique within project"
not_unique_within_space: "must be unique within space"
unknown_download_error: "An unexpected error occurred while downloading the file. Please try again later or contact support if the issue persists."
unrecognized_fabric_addresses: "One or more of the provided fabric addresses is unrecognized. Check that all IDs are valid and belong to the current project."
unsupported_file_extension: "Unsupported file extension (%{extension}). Allowed extensions are: %{allowed_extensions}."
unsupported_mode: is not a supported mode on this number
unsupported_option: %{option} is not a supported option
unsupported_region: must be from an allowed region
upload_error: Error while uploading file
uri_does_not_resolve_to_address: The provided URI does not resolve to a recognized address.
uri_does_not_resolve_to_resource: The provided URI does not resolve to a valid resource.
uri_resolves_to_unsupported_resource: The provided URI resolves to a resource that is unsupported for dialing.
url_failed_to_parse: An unknown error occurred when parsing the provided URL.
url_is_unsafe: must not point to internal/private networks.
verification_request_too_soon: has received a verification call too recently. Please wait a minute before requesting another callReason for the request
We did an audit across all the endpoints to ensure consistent code usage, specific codes, and descriptive error messages.
Sections to be updated
SW REST API Error Codes
Related Issues or PRs
https://github.com/signalwire/cloud-product/issues/16967
Please feel free to reach out with any questions!