Errors
The Prelude’s V2 API error format and the various error codes returned.
Codes
Below is a list of possible error codes, along with additional information about how to resolve them.| Code | Description |
|---|---|
batch_size_exceeded | The batch size is too large. The maximum batch size is 1000. |
blocked | The verification attempt was blocked. This error only occurs when using the Supabase integration. |
category_forbidden | The message category is not allowed for marketing messages in the specified country. |
channel_not_enabled_in_region | The channel you’re trying to use is not activated in the region you’re trying to deliver the message. You can update the channels in the Dashboard from the route settings. |
channels_conflict | Channels and preferred channel can’t be set at the same time. |
channels_not_allowed | The channels option is not allowed for this account. Contact us to discuss your use case. |
custom_code_not_allowed | The custom_code feature is not enabled on your account. Contact support for information. |
custom_size_conflict | Custom code and code size can’t be set at the same time. |
custom_suffix_not_enabled | Custom suffixes are not enabled on your account. Contact support to enable them. |
document_not_supported | This template does not support document attachments. Remove the document object. |
document_required | This template requires a document attachment. Provide a document object with url and filename. |
email_verification_not_allowed | The email verification feature is not available to your account. Contact support for more information. |
empty_batch | The batch is empty. Provide at least one phone number. |
expires_at_in_past | The expires_at parameter is in the past. Provide a future date. |
expires_at_too_far_in_future | The expires_at parameter is too far in the future. Provide a date within the next day. |
feature_gated | Your account does not have access to this feature. Contact support for more information. |
flow_not_found | The requested Watch flow does not exist. |
force_challenge_not_allowed | The force_challenge option is not allowed for this account. Contact us to discuss your use case. |
impossible_code | The provided code is impossible. |
insufficient_balance | You do not have a sufficient balance to send this message. Top-up your account from the Dashboard. |
internal | An internal error occurred. Please try again later. |
invalid_api_key | The provided API key is invalid. You can get your API key from the Dashboard. |
invalid_app_realm | Both platform and value are required for app realm. |
invalid_app_realm_platform | AppRealm platform must be “android” or “web”. |
invalid_app_realm_value | The AppRealm value is invalid. Must be an 11 character base64 string for Android, or a valid origin domain for Web. |
invalid_app_version | The provided app version is invalid. |
invalid_bearer_token | The provided bearer token is invalid. |
invalid_callback_url | The provided callback URL is invalid. |
invalid_channels | The provided channels are invalid. Each entry must be a supported channel and must appear only once. |
invalid_code_size | Code size must be between 4 and 8. |
invalid_correlation_id | The provided correlation ID is invalid. Provide a string with a maximum length of 80 characters. |
invalid_custom_code | The provided custom code is invalid. |
invalid_customer_uuid | The provided customer UUID is invalid. This error only occurs when using the Supabase integration. |
invalid_date_format | The date passed is not a valid RFC3339 date. |
invalid_default_sender_id | The template default Sender ID is invalid. Provide a valid Sender ID. |
invalid_device_id | The provided device ID is invalid. |
invalid_device_model | The provided device model is invalid. |
invalid_device_platform | The provided device platform is invalid. |
invalid_device_type | The provided device type is invalid. |
invalid_dispatch_id | The provided dispatch identifier is invalid. Must be a valid UUIDv7. |
invalid_document_url | The provided document URL is invalid. Provide a valid HTTP or HTTPS URL. |
invalid_email | The provided email address is invalid. |
invalid_flow | The provided Watch flow is invalid. See details field for more information. |
invalid_integration | The provided integration is invalid. |
invalid_ja4_fingerprint | The provided JA4 fingerprint is invalid. |
invalid_line_type | The provided phone number is not assigned to a mobile phone. Prelude only supports mobile phone numbers. |
invalid_locale | The provided locale is invalid. Locales should be a BCP-47 formatted string. |
invalid_max_auto_fallbacks | The max_auto_fallbacks parameter must be a positive integer or zero. |
invalid_method | The provided method is invalid. |
invalid_os_version | The provided OS version is invalid. |
invalid_pagination_cursor | The provided pagination cursor is invalid. |
invalid_pagination_limit | The limit parameter must be between 1 and 200. |
invalid_pagination_offset | The offset parameter must be a non-negative integer. |
invalid_phone_number | The provided phone number is invalid. Provide a valid E.164 phone number. |
invalid_preferred_channel | The provided preferred channel is invalid. |
invalid_psd2 | The submitted psd2 block is invalid. Required for codes issued under the prelude:psd2 template. |
invalid_recipe | The provided Watch recipe is invalid. See details field for more information. |
invalid_request | The request is invalid. Check your request against the API documentation and try again. |
invalid_rule | The provided Watch rule is invalid. See details field for more information. |
invalid_security_suffix_type | The security_suffix_type parameter must be one of ‘none’, ‘basic’, ‘expiration’ or ‘anti_phishing’. |
invalid_sender_id | The provided sender ID is invalid. |
invalid_subscription_config_id | The provided subscription configuration identifier is invalid. |
invalid_subscription_state | The state parameter must be either SUB or UNSUB. |
invalid_suffix | The provided suffix is malformed. It must be 1 to 30 characters long, hold more than digits, and carry no link, control or invisible character. |
invalid_template | The provided template is invalid. The message field explains what to fix. |
invalid_template_field | One of the template parameters is out of range. The param field names it. |
invalid_template_id | The provided template ID is invalid. You can get your template ID from the Dashboard. |
invalid_template_kind | The kind parameter must be one of ‘optimized’, ‘psd2’ or ‘account-takeover’. |
invalid_template_name | The name parameter is required and must not be empty. |
invalid_template_type | The type parameter must be either ‘transactional’ or ‘marketing’. |
invalid_template_variables | The provided template variables are invalid. Provide a JSON object with the required variables. |
invalid_user_agent | The provided user agent is invalid. |
invalid_variables | The provided variables are invalid. |
malformed_verification_target_type | The provided verification target type is invalid. |
managed_rule_read_only | The Watch rule is managed by Prelude and cannot be edited or deleted. |
max_auto_fallbacks_not_allowed | The max_auto_fallbacks option is not allowed for this account. Contact us to discuss your use case. |
missing_api_key | You forgot to include your API key. Add it to the Authorization header using Bearer authentication, like this: Authorization: Bearer <API_KEY>. |
missing_company_details | The template needs registration paperwork and we hold no company details for your account yet. Contact support to register them. |
missing_document_filename | The document filename is required. Provide a filename in the document object. |
not_implemented | The requested feature is not implemented. |
premature_retry | This verification was retried too early. You can set the delay between retries from the Dashboard. |
rate_limited | Rate limit exceeded. Retry the request after the duration specified in the Retry-After header. Contact support if you need higher throughput. |
recipe_in_use | The Watch recipe is still selected by a flow and cannot be deleted. See details field for what refers to it. |
recipe_not_found | The requested Watch recipe does not exist. |
region_blocked_by_customer | This region is blocked for this account. You can change this in the Dashboard from the route settings. |
region_missing_registration | This region needs additional registration. Contact support for information. |
rule_in_use | The Watch rule is still scored over by a recipe and cannot be deleted. See details field for what refers to it. |
rule_not_found | The requested Watch rule does not exist. |
schedule_at_in_past | The schedule_at parameter is in the past. Provide a future date. |
schedule_at_too_far_in_future | The schedule_at parameter is too far in the future. Provide a date within the next 90 days. |
spending_limit_exceeded | The spending limit for a time period has been exceeded. You can set the spending limits from the Dashboard. Retry-After: <seconds> field will be provided in headers. |
subscription_config_not_found | No subscription configuration was found. |
subscription_status_not_found | No subscription status was found for the provided phone number. |
suffix_not_allowed | The provided suffix looks like another company or a public institution. Contact support if it belongs to you. |
suffix_script_not_supported | The provided suffix is written in an alphabet we do not support yet. Contact support so we can add it. |
supabase_not_enabled | The Supabase integration is not enabled for this account. |
suspended_account | Your account is suspended. Contact support for more information. |
template_not_editable | Only a template in draft status can be edited, deleted or submitted. |
template_not_found | The provided template ID was not found. |
template_not_registered_in_country | The provided template is not registered in the requested country. |
template_not_validated | The provided template has not been validated. Contact support for more information. |
too_many_attempts | You have reached the maximum number of retries for this verification window. You can try again in a few minutes. |
too_many_checks | You have reached the maximum number of checks for this verification window. You can try again in a few minutes. |
too_many_configuration_changes | You have reached the maximum number of configuration changes for today. You can try again tomorrow. |
too_many_suffix_changes | You have reached the maximum number of suffix changes for today. You can try again tomorrow. |
trusted_user_signal_not_allowed | The is_trusted_user signal is not allowed for this account. Contact us to discuss your use case. |
unassigned_phone_number | The provided phone number does not belong to a valid, assigned number range. |
unauthorized_sender_id | The provided sender ID is not authorized to send messages. Contact support for more information. |
unsubscribed | The provided phone number is unsubscribed. |
unsupported_country | Prelude does not support sending messages to the provided country yet. Contact support for more information. |
voice_channel_unavailable | Voice is not available for this verification. Use a message-based verification instead. |
The error code.
Example:
"invalid_phone_number"
A human-readable message describing the error.
Example:
"The provided phone number is invalid. Provide a valid E.164 phone number."
The error type.
Example:
"bad_request"
A string that identifies this specific request. Report it back to us to help us diagnose your issues.
Example:
"3d19215e-2991-4a05-a41a-527314e6ff6a"
The parameter the error refers to, when it applies to a single one.
Example:
"phone_number"
⌘I
{
"code": "invalid_phone_number",
"message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
"type": "bad_request",
"request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
"param": "phone_number"
}