Error Catalog

This catalog is the canonical reference for Sent API v3 error codes. Every documented code appears below with its cause and step-by-step remediation; other documentation pages link to this catalog rather than restating code details.

The same codes also explain outcomes that happen after a request succeeds. A message that ends FAILED, FILTERED or BLOCKED reports why as reason_code and reason, and so does a channel that is not ACTIVE. A cause the API rejects synchronously keeps its code there: an opted-out recipient is BUSINESS_004 on a refused request and on a filtered message alike. Codes only an outcome can have are listed under Message Outcome Codes and Channel Status Reasons. A phone call that ends without completing reports why as failure_reason; those values are under Call Failure Reasons. Branch on reason_code; the wording of reason may improve, but a code never changes meaning.

Authentication Errors

AUTH_001: User is not authenticated

Error Message: "User is not authenticated"

HTTP Status: 401 Unauthorized

Cause: The request reached an endpoint without an authenticated identity, for a reason other than the API key. A request with no API key, or an unrecognized one, returns AUTH_002 instead, whichever header it used. On v3 you see AUTH_001 when the voice token on an in-app calling request is invalid or expired, and as the fallback code for any other 401.

Remediation:

1. If the message is Invalid or expired voice token, mint a new voice token on your backend and retry. See In-app calls
2. If you expected your API key to authenticate the request, check error.code: a key problem is reported as AUTH_002, so follow its remediation below

AUTH_002: Invalid or missing API key

Error Message: "Invalid or missing API key"

HTTP Status: 401 Unauthorized

Cause: The request carries no API key in either header, or the key it carries is invalid, revoked, or not recognized.

Remediation:

1. Send the API key on every request, in the x-api-key header or as Authorization: Bearer <key>. Any other Authorization scheme counts as no key
2. Verify your API key is correct and complete
3. Check that you're using the API key for the correct environment (each environment should have its own key)
4. Log into your Sent Dashboard and verify the key is active
5. Generate a new API key if the current one was revoked

Example Fix:

# ❌ Missing key
curl -X GET https://api.sent.dm/v3/me

# ✅ Correct
curl -X GET https://api.sent.dm/v3/me \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# ✅ Also correct
curl -X GET https://api.sent.dm/v3/me \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

AUTH_004: Insufficient permissions

Error Message: "Insufficient permissions for this operation"

HTTP Status: 403 Forbidden

Cause: Your user role doesn't have permission to perform this operation.

Remediation:

1. Check your organization role (owner, admin, developer, billing)
2. Contact your organization owner to request additional permissions
3. Some operations require the owner or admin role

See: Roles and Permissions for the operations each role can perform and how to look up your own role

AUTH_005: Account not yet activated

Error Message: "Your account is not yet activated. Please wait for account activation before using the API."

HTTP Status: 403 Forbidden

Cause: The API key is valid and channel setup is complete, but the account is still pending final activation by Sent.

Remediation:

1. You have completed all required setup steps, so no action is needed from your side
2. Wait for the activation confirmation email from Sent
3. Contact support@sent.dm if activation takes longer than expected

AUTH_006: KYC verification not complete

Error Message: "Your KYC verification is not complete. Please submit your KYC documents before using the API."

HTTP Status: 403 Forbidden

Cause: The API key is valid but the account has not completed KYC verification. Applies to accounts in status: SIGNED_UP, KYC_STARTED, WHITELISTED, ONBOARDING_STARTED, or KYC_RESUBMISSION_REQUESTED.

Remediation:

1. Log into your Sent Dashboard and complete the KYC verification flow
2. If resubmission was requested, address the flagged items and resubmit your documents
3. Contact support@sent.dm if you need assistance with KYC

AUTH_007: Channel setup not complete

Error Message: "Your channel setup is not complete. Please configure at least one messaging channel before using the API."

HTTP Status: 403 Forbidden

Cause: The API key is valid and KYC is approved, but no messaging channel (SMS or WhatsApp) has been configured. Applies to accounts in status: KYC_COMPLETED or MESSAGE_COMPLIANCE_COMPLETED.

Remediation:

1. Log into your Sent Dashboard and complete channel setup
2. Configure at least one SMS or WhatsApp sender
3. See Channel Setup for step-by-step instructions

Validation Errors

VALIDATION_001: Request validation failed

Error Message: "Request validation failed"

HTTP Status: 400 Bad Request. Also returned with:

• 413 Payload Too Large and the message "Request body is too large" when the request body exceeds the endpoint's size limit.
• 422 Unprocessable Entity from POST /v3/sender-profiles and POST /v3/channels/sms when a compliance document the market requires was not uploaded, or an uploaded file was rejected. details names each affected document or file.

Cause: The request body or parameters failed validation. Check the details field for specific field-level errors.

Remediation:

1. Review the error.details object for field-specific error messages
2. Ensure all required fields are provided
3. Verify data types match the schema (for example, strings vs numbers)

Example:

{
  "error": {
    "code": "VALIDATION_001",
    "message": "Request validation failed",
    "details": {
      "to": ["'to' must contain at least one recipient"],
      "template": ["'template' must have either 'id' (non-empty GUID) or 'name' (non-empty string)"]
    }
  }
}

VALIDATION_002: Invalid phone number format

Error Message: "Invalid phone number format"

HTTP Status: 400 Bad Request

Cause: The phone number is not in a valid format.

Remediation:

1. Use E.164 format: +1234567890
2. Include the country code (for example, +1 for US)
3. Remove any non-numeric characters except the leading +

Valid Examples:

• +1234567890 (US)
• +447911123456 (UK)
• +919876543210 (India)

VALIDATION_003: Invalid GUID format

Error Message: "Invalid GUID format"

HTTP Status: 400 Bad Request

Cause: A UUID field contains an invalid format.

Remediation:

1. Ensure UUIDs follow the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
2. Verify the UUID is complete (36 characters including hyphens)
3. Check that you're not passing an empty string or null

Valid Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

VALIDATION_004: Required field is missing

Error Message: "Required field is missing"

HTTP Status: 400 Bad Request

Cause: A required field is not present in the request body.

Remediation:

1. Check the API documentation for required fields
2. Ensure the field name is spelled correctly (snake_case)
3. Verify the field is not null or undefined

VALIDATION_005: Field value out of valid range

Error Message: "Field value out of valid range"

HTTP Status: 400 Bad Request

Cause: A numeric field value is outside the allowed minimum/maximum range.

Remediation:

1. Check the API documentation for valid ranges
2. For retry_count: must be between 1 and 5
3. For timeout_seconds: must be between 5 and 120
4. Ensure integer values are not negative where prohibited

Example:

{
  "error": {
    "code": "VALIDATION_005",
    "message": "Field value out of valid range",
    "details": {
      "retry_count": ["Value must be between 1 and 5"]
    }
  }
}

VALIDATION_006: Invalid enum value

Error Message: "Invalid enum value"

HTTP Status: 400 Bad Request

Cause: A field value is not one of the allowed enum values.

Remediation:

1. Check the API documentation for allowed values
2. Verify the value matches exactly (case-sensitive)
3. Common enums: channel (sent, sms, whatsapp, rcs), template category (MARKETING, UTILITY, AUTHENTICATION)

VALIDATION_008: Invalid template variable value

Error Message: varies by cause (see below)

HTTP Status: 400 Bad Request. Also reported as the reason_code of a FAILED message, when variables are found missing or invalid after the send was accepted with 202.

Cause: A supplied template variable value is rejected before the message is accepted. Three distinct causes share this code, and the message tells you which one applies:

Remediation:

1. Read the variable name from the error message. It names every offending variable, so you can fix them in one pass rather than one send at a time.
2. For a pattern mismatch, check the variable's pattern on the template and confirm the value matches it.
3. For invalid text, strip newlines, carriage returns, and tabs from the value, and collapse any run of more than four spaces. These are rejected because WhatsApp does not accept them in a parameter. The rule applies to template variables only: free-form text keeps its line breaks, tabs, and spacing on every channel.
4. For an empty value on WhatsApp, supply a non-empty value or omit the variable if the template does not require it. WhatsApp rejects a text parameter with no text, so the send can never succeed.

VALIDATION_011: Voice identity is invalid

Error Message: "Voice identity is invalid"

HTTP Status: 400 Bad Request

Cause: An app user's identity is empty, longer than 200 characters, or contains something other than letters, digits, - and _. It is checked on identity of POST /v3/channels/voice/tokens and on to.value of POST /v3/calls/{id}/participants when to.kind is user. The identity names the user in every call, so only characters that survive a URL and a token unchanged are accepted.

Remediation:

1. Read error.details for the field at fault.
2. Use your own stable user id, such as agent-42, with letters, digits, hyphens, and underscores only.
3. Keep it to 200 characters or fewer.

Resource Errors

RESOURCE_001: Contact not found

Error Message: "Contact not found"

HTTP Status: 404 Not Found

Cause: The specified contact ID doesn't exist or doesn't belong to your account.

Remediation:

1. Verify the contact ID is correct
2. List all contacts to find the correct ID: GET /v3/contacts
3. Check that you're using the correct API key for the account that owns the contact

Debug Steps:

# List contacts to find valid IDs
curl -X GET https://api.sent.dm/v3/contacts \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

RESOURCE_002: Template not found

Error Message: "Template not found"

HTTP Status: 404 Not Found

Cause: The specified template ID doesn't exist.

Remediation:

1. Verify the template ID is correct
2. List all templates: GET /v3/templates
3. Ensure the template hasn't been deleted

RESOURCE_003: Message not found

Error Message: "Message not found"

HTTP Status: 404 Not Found

Cause: The specified message ID doesn't exist.

Remediation:

1. Verify the message ID is correct
2. Note that message IDs are only available after sending
3. Messages may be purged after retention period
4. A message ID that belongs to another account also returns this error rather than 403, so the response does not reveal whether the ID exists

RESOURCE_004: Customer not found

Error Message: "Customer not found"

HTTP Status: 404 Not Found

Cause: The specified customer ID doesn't exist or is not accessible.

Remediation:

1. Verify the customer ID is correct
2. Check that your API key has access to this customer
3. Contact support if the customer should exist

RESOURCE_005: Organization not found

Error Message: "Organization not found"

HTTP Status: 404 Not Found

Cause: The specified organization ID doesn't exist or you don't have access.

Remediation:

1. Verify the organization ID is correct
2. Ensure you're using an organization-level API key
3. Check that your account is a member of the organization

RESOURCE_006: User not found

Error Message: "User not found"

HTTP Status: 404 Not Found

Cause: The specified user ID doesn't exist in your organization.

Remediation:

1. Verify the user ID is correct
2. List organization users to find valid IDs
3. The user may have been removed from the organization

RESOURCE_007: Resource already exists

Error Message: "Resource already exists"

HTTP Status: 409 Conflict

Cause: Attempting to create a resource that already exists (for example, a duplicate contact).

Remediation:

1. Check if the resource already exists using a list or get endpoint
2. Update the existing resource instead of creating
3. Use a unique identifier for your idempotency key

RESOURCE_008: Webhook not found

Error Message: "Webhook not found"

HTTP Status: 404 Not Found

Cause: The specified webhook ID doesn't exist.

Remediation:

1. Verify the webhook ID is correct
2. List all webhooks: GET /v3/webhooks
3. Check if the webhook was deleted

RESOURCE_009: Brand not found

Error Message: "Brand not found for this profile"

HTTP Status: 404 Not Found

Cause: No 10DLC brand is registered for the profile, and none is inherited from its organization.

Remediation:

1. Register the brand first; see the 10DLC Registration Guide
2. Confirm you are targeting the right profile with GET /v3/profiles

RESOURCE_010: Campaign not found

Error Message: "Campaign not found for this profile"

HTTP Status: 404 Not Found

Cause: The specified campaign ID doesn't belong to this profile's brand.

Remediation:

1. List the profile's campaigns and reuse the returned id
2. Verify the campaign belongs to the brand registered for this profile

RESOURCE_011: Batch not found

Error Message: "Batch not found"

HTTP Status: 404 Not Found

Cause: The specified batch SMS operation doesn't exist.

Remediation:

1. Verify the batch ID is correct
2. Check whether the batch has expired or was already processed

RESOURCE_012: Phone number not found

Error Message: "Phone number not found"

HTTP Status: 404 Not Found

Cause: The specified phone number isn't provisioned on your account.

Remediation:

1. List your numbers to confirm the exact value
2. Use E.164 format (for example, +14155550123)

RESOURCE_013: Resource not found

Error Message: "Resource not found"

HTTP Status: 404 Not Found

Cause: Generic not-found fallback, returned when no more specific code applies.

Remediation:

1. Verify the resource ID in the request path
2. Check the endpoint path is correct for the resource type

RESOURCE_014: Profile not found

Error Message: "Profile not found"

HTTP Status: 404 Not Found

Cause: The specified profileId isn't a child profile of your organization. Passing your organization's own ID also fails.

Remediation:

1. Use a profile ID returned by GET /v3/profiles
2. Confirm the profile belongs to your organization

RESOURCE_015: Call not found

Error Message: "Call not found"

HTTP Status: 404 Not Found

Cause: No call with this id belongs to your account. A call that belongs to another account is reported as not found rather than forbidden, so an id never reveals whether it exists.

Remediation:

1. Use the id from the call.request question, a call.* webhook, or GET /v3/calls. It has the form call_ followed by a GUID.
2. Send the request with the API key of the account the call belongs to.

RESOURCE_017: Participant not found

Error Message: "Participant not found"

HTTP Status: 404 Not Found

Cause: The participantId on PATCH or DELETE /v3/calls/{id}/participants/{participantId} is not a live participant of this call's conference room. A participant in another room or another account answers the same way, and so does one who has already left.

Remediation:

1. List the room with GET /v3/calls/{id}/participants and use an id from that list.
2. Treat a 404 on remove as done: the participant is no longer in the room.

Business Logic Errors

BUSINESS_002: Rate limit exceeded

Error Message: "Rate limit exceeded"

HTTP Status: 429 Too Many Requests

Cause: You've exceeded the allowed number of requests per minute.

Remediation:

1. Check the Retry-After header for wait time
2. Implement exponential backoff in your code
3. Consider using webhooks instead of polling
4. Contact support if you need higher limits

See: Rate Limits Documentation

BUSINESS_003: Insufficient account balance

Error Message: "Insufficient balance"

HTTP Status: 402 Payment Required

Cause: Your account doesn't have enough credit to complete the operation.

Note: POST /v3/messages does not return this error. Sends are accepted with 202; when the balance is insufficient, each message is finalized asynchronously as BLOCKED with reason_code: "BUSINESS_003" and clears after a top-up. Legacy v2 send endpoints reject an out-of-balance request synchronously with this error.

Remediation:

1. Check your current balance and add funds in Billing → Overview (the balance is not exposed through the API)
2. Review pricing for the operation you're attempting

BUSINESS_004: Contact has opted out

Error Message: "Contact has opted out of messaging"

HTTP Status: 400 Bad Request

Cause: An operation targeted a contact that has opted out of messaging.

Note: POST /v3/messages does not return this error. Sends are accepted with 202 regardless of recipient opt-out state, and each consent-blocked message is finalized asynchronously as FILTERED with reason_code: "BUSINESS_004" (see ERR_CONSENT_BLOCKED below).

Remediation:

1. Inspect the affected contacts via GET /v3/contacts/{id} and confirm their opt_out status.
2. Remove opted-out contacts from your messaging lists.
3. Re-engagement requires the contact to opt back in through a STOP/START style flow or via an opt_out: false update to the contact (where you have a verifiable record of new consent).

ERR_CONSENT_BLOCKED: Per-message consent block

Where it surfaces:

• GET /v3/messages/{id}: status = FILTERED, with reason_code: "BUSINESS_004"
• GET /v3/messages/{id}/activities: a FILTERED activity carrying the same reason_code and reason
• The message.filtered webhook event, with payload.reason_code: "BUSINESS_004"

ERR_CONSENT_BLOCKED itself is the internal classification and never appears in a response or payload. What you see is BUSINESS_004, the same code an opted-out contact returns elsewhere in the API. A FILTERED message whose reason_code is DELIVERY_004 was stopped by a routing rule rather than by consent.

Cause: The send-time consent policy refused this individual message because the recipient's contact has opt_out = true or their phone is on the customer's phone-channel suppression list. The check runs pre-routing, so no provider call is made and the customer is not charged.

Remediation:

1. Stop targeting this contact until they re-confirm consent.
2. If the opt-out is incorrect (for example, test data), update the contact's opt_out field through PATCH /v3/contacts/{id}. Only do this when you have a verifiable record of renewed consent.
3. For phone-level suppression entries that should be removed, contact support.

BUSINESS_005: Template not approved

Error Message: "Template not approved for sending"

HTTP Status: 400 Bad Request

Cause: The WhatsApp template hasn't been approved yet.

Remediation:

1. Check template status: GET /v3/templates/{id}
2. Wait for WhatsApp/Meta approval (typically 24-48 hours)
3. For urgent needs, use SMS channel instead
4. Review template guidelines to ensure approval

BUSINESS_006: Message cannot be resent or cancelled in its current state

Error Messages:

HTTP Status: 409 Conflict

Cause: A resend or cancel targeted a message whose current state doesn't allow it.

Remediation:

1. For a FILTERED message, don't retry the resend; a FILTERED message is always refused. Check its reason_code with GET /v3/messages/{id} to see why it was filtered.
2. For a message still in flight, held for quiet hours, or sent less than 15 minutes ago, wait and retry the resend later.
3. On cancel, only a message that is currently SCHEDULED can be cancelled. Read the current status with GET /v3/messages/{id}: a message that has left SCHEDULED never returns to it, so retrying returns the same error. See Cancelling scheduled messages.
4. Send a new message with POST /v3/messages if you need to make changes.

BUSINESS_007: Channel not available

Error Message: "Sending from {COUNTRY} as {type} is not available yet. Contact support if you expected it to be."

HTTP Status: 503 Service Unavailable, from GET /v3/compliance/requirements. Also reported as the reason_code of a FAILED message.

Cause:

• On GET /v3/compliance/requirements: the requested country and number type market is not available yet.
• On a message: the send needed MMS, and MMS is not enabled for the account.

Remediation:

1. For the compliance requirements request, contact support if you expected the market to be available.
2. For a message, contact support@sent.dm to enable MMS on the account. See Sending MMS.

BUSINESS_008: Operation would exceed quota

Error Message: "Operation would exceed quota"

HTTP Status: 400 Bad Request

Cause: The operation would exceed your account's quota limits, such as those for messages, contacts, or templates.

Remediation:

1. Check your current usage in the Dashboard
2. Upgrade your plan to increase quotas
3. Delete unused resources to free up quota
4. Contact support for temporary quota increases

BUSINESS_009: Feature not supported

Error Message: "Compliance requirements for the {channel} channel are not published yet. Only "sms" is available here."

HTTP Status: 501 Not Implemented, from GET /v3/compliance/requirements. Also reported as the reason_code of a FAILED message.

Cause:

• On GET /v3/compliance/requirements: channel was set to a channel other than sms. Only SMS has published compliance requirements.
• On a message: the channel does not support this kind of message; the message type or operation is not available for this sender or destination.

Remediation:

1. For the compliance requirements request, omit channel or set it to sms.
2. For a message, read its reason for the likely cause, and send the content on a channel or sender that supports it.

BUSINESS_010: Webhook is inactive

Error Message: "Webhook is inactive"

HTTP Status: 400 Bad Request

Cause: The operation targets a webhook that is not active. Sending a test event to an inactive webhook returns this code. A webhook can be inactive because you turned it off, or because Sent turned it off automatically after repeated delivery failures.

Remediation:

1. Check the webhook's status on the Webhooks page in the Dashboard.
2. If Sent turned it off automatically, fix the endpoint first: confirm it is reachable and returns a 2xx within the timeout. Then turn the webhook back on. Turning it back on without fixing the endpoint will lead to Sent turning it off again.
3. Re-send the test event once the webhook is active.

BUSINESS_011: Destination country is not allowed

Error Message: "Calls and messages to the destination country are not allowed"

HTTP Status: 400 Bad Request, from POST /v3/calls/{id}/participants. Also reported as the reason_code of a FAILED message.

Cause:

• On a call, the phone participant's number is in a country Sent does not allow calls to. A connectToNumber answer to such a destination is an invalid answer, reported as destination_blocked by the test endpoint, and the call fails with invalid_answer. A call placed from your app straight to such a number is refused before your callback is asked and fails with destination_blocked.
• On a message, WhatsApp refused it because the WhatsApp business account is restricted from messaging recipients in the destination country.

Remediation:

1. Check the destination number and its country code.
2. For a message, check the business account's restrictions in WhatsApp Business Manager.
3. Contact support@sent.dm if you expected the destination country to be allowed.

BUSINESS_012: Template is not active on the requested channel

Error Message: "This template is not active on the requested channel"

HTTP Status: 400 Bad Request

Cause: The template exists and is approved, but not on the channel this send is pinned to. Template approval is per channel, so a template approved for SMS is not automatically usable on WhatsApp.

Remediation:

1. Check the template's per-channel status with GET /v3/templates/{id}.
2. Send on a channel where the template is active, or omit channel to let Sent choose one that is.
3. If you need the template on that channel, submit it for approval there and wait for it to be approved.

WHATSAPP_TEMPLATE_REQUIRED: Free-form WhatsApp outside Meta's window

Error Message: "Free-form WhatsApp messages are only allowed within 24 hours of the user's latest inbound WhatsApp message. Send an approved template instead."

HTTP Status: Not returned on an HTTP response. POST /v3/messages accepts the batch with 202, and this code arrives as the terminal FAILED status on the individual message.

Cause: A free-form message (text rather than template) was sent with channel: "whatsapp" while Meta's 24-hour customer-service window was shut. Only an inbound WhatsApp message from the contact opens that window; an outbound template does not.

Meta can also reject a send that Sent considered inside the window, returning error 131047 (re-engagement required). Sent surfaces that as this same code, so treat it as one condition with one fix.

Where it surfaces: the message's terminal status. GET /v3/messages/{id} reports status: "FAILED" with reason_code: "WHATSAPP_TEMPLATE_REQUIRED", and the message.failed webhook carries the same payload.reason_code and payload.reason.

Remediation:

1. Send an approved WhatsApp template instead. A template is always accepted, window or no window.
2. Omit channel to let Sent choose. An auto-detect send falls back to RCS or SMS when Meta's window is shut, so the message still goes out if the contact is reachable there.
3. Wait for the contact to message you on WhatsApp, which re-opens the window for 24 hours.

CONVERSATION_TEMPLATE_REQUIRED: No open conversation

Error Messages:

HTTP Status: Not returned on an HTTP response. POST /v3/messages accepts the batch with 202, and this code arrives as the terminal BLOCKED status on the individual message. The gate runs before routing, so nothing reaches a carrier and the message is excluded from your deliverability rate; it fires message.blocked, not message.failed.

Cause: A free-form message (text rather than template) was sent on SMS, RCS, or with channel omitted to a contact who has never replied, and either no approved template was ever sent to them or the last one is more than 7 days old. A contact who has replied at any point in the past is never blocked by this gate. Your own free-form messages do not count as templates, and neither leg of a STOP exchange counts as a reply.

Where it surfaces: the message's terminal status. GET /v3/messages/{id} reports status: "BLOCKED" with reason_code: "CONVERSATION_TEMPLATE_REQUIRED", and the message.blocked webhook carries the same payload.reason_code and payload.reason.

Remediation:

1. Send an approved template to open or re-open the conversation. Free-form text is then accepted for 7 days, and indefinitely once the contact replies.
2. Do not retry the same free-form send. It will keep being blocked until a template or a reply from the contact opens the conversation.
3. This only affects contacts who have never replied, so it is most common on cold outreach; see Conversation Windows.

BUSINESS_014: Account is suspended

Error Message: "This account is suspended"

HTTP Status: 403 Forbidden

Cause: The account is suspended and cannot send messages or create templates.

Remediation:

1. Contact support. A suspension is not something you can clear through the API.
2. Do not retry the request. Every send will return this code until the suspension is lifted, so a retry loop will not recover.

BUSINESS_015: Market not supported

Error Message: "This country and number type combination is not available"

HTTP Status: 422 Unprocessable Entity, from POST /v3/sender-profiles. Also reported as the reason_code of a FAILED message.

Cause:

• On POST /v3/sender-profiles: the channels.sms block asks for a number type that is not available in the requested country. details names the market. Nothing is created.
• On a message: messaging to the destination country or region is not supported for this sender.

Remediation:

1. Choose a different country or number type, or contact support to request the market.

BUSINESS_016: Sender type not supported

Error Message: "This number type cannot be provisioned yet"

HTTP Status: 422 Unprocessable Entity

Cause: POST /v3/sender-profiles asked for a channels.sms.number_type that can't be provisioned in any country. details lists the number types that can. Nothing is created.

Remediation:

1. Ask for one of the number types listed in details.
2. Omit the channels.sms block to create a profile that sends through the shared routes for its country.

BUSINESS_017: WhatsApp business account unavailable

HTTP Status: Not returned on an HTTP response. Reported as the reason_code of a FAILED message.

Cause: The WhatsApp business account cannot send at the moment: WhatsApp has restricted or locked it (for example, over a policy violation), its payment method has a problem, or it is in maintenance.

Remediation:

1. Check the account's status and payment method in WhatsApp Business Manager.
2. Omit channel so auto-detect can send over another channel while WhatsApp is unavailable.

BUSINESS_018: WhatsApp marketing messages disabled

HTTP Status: Not returned on an HTTP response. Reported as the reason_code of a FAILED message.

Cause: Marketing sends are switched off for this WhatsApp business account.

Remediation:

1. Enable marketing messages for the account in WhatsApp Business Manager.
2. Until then, send UTILITY or AUTHENTICATION templates, or send marketing over another channel.

BUSINESS_019: Sender not configured for the channel

HTTP Status: Not returned on an HTTP response. Reported as the reason_code of a FAILED message.

Cause: The sender is not set up to send on the channel the message was routed to: the number or sender ID is invalid, not enabled for messaging or temporarily unusable; its 10DLC, toll-free or sender ID registration is missing or incomplete; or, on WhatsApp, the business number is not registered or has no approved display name.

Remediation:

1. Check the channel with GET /v3/channels. A market that is not ACTIVE carries a reason_code saying what it's waiting on (see Channel Status Reasons).
2. Contact support@sent.dm with the message ID if the channel reports ACTIVE.

BUSINESS_020: Onboarding message limit reached

HTTP Status: Not returned on an HTTP response. Reported as the reason_code of a BLOCKED message.

Cause: The account has sent as many messages as its current onboarding stage allows. It has finished KYC or channel setup, but not the step after, which lifts the limit.

Remediation:

1. Complete the next onboarding step in the Sent Dashboard.
2. Check the blocked messages with GET /v3/messages/{id} once the limit is lifted, and resend any that are still BLOCKED.

BUSINESS_022: Phone number is not owned by this account

Error Message: "Phone number is not owned by this account"

HTTP Status: 400 Bad Request

Cause: POST /v3/channels/voice named a number you do not hold, or POST /v3/calls/{id}/participants named a caller_id that is not one of your numbers. A connectToNumber answer whose callerId you do not own is an invalid answer instead, reported as caller_id_not_owned by the test endpoint, and the call fails with invalid_answer.

Remediation:

1. List the numbers you hold with GET /v3/channels.
2. To take calls on a new number instead, leave number out of POST /v3/channels/voice, optionally with an area_code.
3. For a participant or a callerId, use one of your own numbers, or omit the field and the call's owning number is used.

BUSINESS_023: Phone calls are not enabled for this account

Error Message: "Phone calls are not enabled for this account"

HTTP Status: 403 Forbidden

Cause: POST /v3/channels/voice/tokens or POST /v3/channels/voice/{number}/test was called while the account has no active voice number.

Remediation:

1. Turn calls on for a number with POST /v3/channels/voice. See Voice.

BUSINESS_024: Phone number is not voice-enabled for this account

Error Message: "Phone number is not voice-enabled for this account"

HTTP Status: 400 Bad Request

Cause: The number is not one of your active voice numbers. POST /v3/channels/voice/tokens (for number) and POST /v3/channels/voice/{number}/test return it for a number that never had calls turned on and for one that was turned off. POST /v3/channels/voice/{number}/rotate-secret returns it for a number that never had calls turned on.

Remediation:

1. List your voice numbers with GET /v3/channels/voice.
2. Turn calls on for the number with POST /v3/channels/voice, or use a number from the list.

BUSINESS_025: The participant could not be added to the call

Error Message: "The participant could not be added to the call"

HTTP Status: 400 Bad Request

Cause: POST /v3/calls/{id}/participants passed every check on Sent's side, but the request to dial the participant into the room was refused when it was placed. A participant who is busy or does not answer is not this error: by then the request was accepted with 202, and that outcome arrives later as the participant leg's call.failed.

Remediation:

1. Check the destination number or identity, and that an app user is registered.
2. Retry. Contact support@sent.dm with the request ID if it repeats.

BUSINESS_026: Call recording is not available

Error Message: "Call recording is not available"

HTTP Status: 403 Forbidden

Cause: POST /v3/calls/{id}/recordings was called, to start or to stop, while call recording is not available. An answer that asks for a recording still connects the call, without the recording.

Remediation:

1. Contact support@sent.dm if you need call recording.
2. Until it is available, do not rely on record: true or startRecording in your answers.

BUSINESS_027: The number could not be set up to receive calls

Error Message: "The number could not be set up to receive calls; try again shortly"

HTTP Status: 502 Bad Gateway

Cause: POST /v3/channels/voice could not attach the number to Sent's voice service, which is what routes a call on it to your callback. Nothing was written, so the number is not half on.

Remediation:

1. Repeat the request. Your request was right, and a retry usually succeeds.
2. Contact support@sent.dm with the request ID if it keeps failing.

BUSINESS_028: No phone number is available for the requested area

Error Message: "No phone number is available for the requested area; try another area code"

HTTP Status: 409 Conflict

Cause: POST /v3/channels/voice without number asked for a new number, and none could be had for the country and area_code. Nothing was bought and nothing was charged.

Remediation:

1. Try another area_code.
2. Omit area_code to take a number from anywhere in the country.

BUSINESS_029: Requested sender is not available on this account

Error Message: "One of the numbers in the channels 'from' list is not a valid sender for that channel"

HTTP Status: Not returned on an HTTP response. Reported as the reason_code of a BLOCKED message.

Cause: A POST /v3/messages request listed a number in a channels.sms entry's from that is not an active SMS number on your account. The number may have been released, may belong to another account, or may never have existed; the reason does not say which. The message's reason names the number by its position, for example channels.sms[0].from[1] is not a valid sms sender. The whole message is blocked, nothing is sent from the other listed numbers, and nothing is charged.

Remediation:

1. Check the number at that position against your active SMS numbers in GET /v3/channels/sms.
2. Remove or replace it, and send the message again.

BUSINESS_030: Template is protected and cannot be deleted

Error Message: "Auto-reply (OPT_OUT) templates are required for TCPA compliance and cannot be deleted" or "This template is read-only. It becomes editable after WhatsApp approval"

HTTP Status: 400 Bad Request

Cause: The template is one of the account's OPT_IN, OPT_OUT, or HELP auto-reply templates, which answer the consent keywords TCPA requires and which every account must keep, or it is a LOB template that stays read-only until WhatsApp approves it. The request was well-formed and the template exists. The MCP templates.delete tool returns the same code, and templates.list reports canDelete: false on every template this applies to.

Remediation:

1. Leave the primary OPT_IN, OPT_OUT, and HELP templates in place. Edit their text instead of deleting them.
2. For a LOB template, wait for WhatsApp approval, then edit or delete it.

LIMIT_001: Scheduled message limit exceeded

Error Message: "Scheduled message limit exceeded"

HTTP Status: 429 Too Many Requests

Cause: Accepting the request would push the account's outstanding scheduled messages past the 1,000,000-message cap. This limit applies to messages currently in SCHEDULED status across all senders and recipients on the account.

Remediation:

1. Wait for existing scheduled messages to be released and sent, which reduces the outstanding count.
2. Cancel scheduled messages you no longer need. A cancelled message stops counting toward the limit.
3. Schedule fewer messages at once, or stagger scheduling over time.
4. Contact support if you need a higher limit for your use case.

Conflict Errors

CONFLICT_001: Concurrent idempotent request

Error Message: "A request with this Idempotency-Key is currently being processed. Please retry shortly."

HTTP Status: 409 Conflict

Cause: Another request with the same idempotency key is currently being processed.

Remediation:

1. Wait for the original request to complete
2. Use a unique idempotency key for each distinct operation
3. Don't reuse idempotency keys across different operations

CONFLICT_005: Idempotency key reused for a different request

Error Message: "This Idempotency-Key was already used for a different request. Send a new key for a new operation, or repeat the original request unchanged to receive its response."

HTTP Status: 422 Unprocessable Entity

Cause: The Idempotency-Key was already used within the last 24 hours by a request with a different method, path, query string, or body. The stored response belongs to that first request, so the API neither replays it nor executes this one.

Remediation:

1. Send a new idempotency key for a new operation.
2. To get the original response, repeat the original request unchanged, byte for byte.

See: Idempotency

CONFLICT_006: Template is in review

Error Message: "This template is in review; its definition, category and language are frozen until the review completes"

HTTP Status: 409 Conflict

Cause: A PUT /v3/templates/{id} tried to change the template's definition, category, or language, or to resubmit it with submit_for_review, while it was still with a reviewer. A template counts as in review when its own status is PENDING, and also when its status is something else but any one of its channels is still awaiting a verdict, which is why an APPROVED template can return this. The freeze is checked before anything is written, so a refused request leaves the template exactly as the reviewer sees it.

Remediation:

1. Wait for the review to finish. Subscribe to templates webhook events to learn the outcome per channel rather than polling.
2. Send only name if you need a change now. The display name is editable throughout, including during review.
3. Resubmit after the verdict lands. A REJECTED template is editable again, and an APPROVED one accepts a live edit.

CONFLICT_007: Default line for app calls is in use

Error Message: "This number is the default line for app calls and other voice numbers are active; move the default to another number first"

HTTP Status: 409 Conflict

Cause: PATCH /v3/channels/voice/{number} sent status: "INACTIVE" for the number calls placed from your app go out from, while other voice numbers are active. An account with active voice numbers always has exactly one default, so the default moves by being given to another number, never by being removed.

Remediation:

1. PATCH another active voice number with default_for_app_calls: true.
2. Turn this number off. Turning off your last voice number is allowed; that turns phone calls off.

CONFLICT_008: Call is no longer active

Error Message: "Call is no longer active"

HTTP Status: 409 Conflict

Cause: A hangup, recording or participant command reached a call that has ended, or that ended between your read and the command.

Remediation:

1. Read GET /v3/calls/{id} for the final status. Nothing can change a call once it has ended.
2. Rely on call.completed and call.failed to learn when a call ends, rather than polling.

CONFLICT_009: Call is not in a conference

Error Message: "Call is not in a conference"

HTTP Status: 409 Conflict

Cause: A participant command reached a call your answer connected to a user or a number rather than to a conference room. It can also arrive for a moment right after a connectToConference answer, because the room is recorded on the call as Sent reads the answer.

Remediation:

1. Answer the call.request with connectToConference for calls you want to add participants to.
2. Retry a 409 that arrives within a second or two of answering; the example app retries for a few seconds.

CONFLICT_011: Call has no phone leg

Error Message: "Call has no phone leg"

HTTP Status: 409 Conflict

Cause: POST /v3/calls/{id}/hangup or POST /v3/calls/{id}/recordings reached a call with no leg on the phone network, such as a call between two of your app users. Such a call can be changed only by the apps in it, so the command is refused up front rather than reported as an ended call.

Remediation:

1. End the call from the app with hangup() in @sentdm/voice.
2. Do not ask for a recording of a call between two app users; it cannot be recorded.
3. A call with a phone caller, or one connected to a phone number, accepts both commands.

Service Errors

SERVICE_001: Cache service temporarily unavailable

Error Message: "Cache service temporarily unavailable. Please retry your request."

HTTP Status: 503 Service Unavailable

Cause: The cache backing idempotency processing is unavailable, so the API cannot guarantee your request is not a duplicate. Returned on requests that carry an Idempotency-Key header while the cache is down.

Remediation:

1. Retry the request after a short delay, reusing the same Idempotency-Key
2. Check API Status for known issues

Internal Errors

INTERNAL_001: Unexpected internal server error

Error Message: "Unexpected internal server error"

HTTP Status: 500 Internal Server Error

Cause: An unexpected error occurred on the server.

Remediation:

1. Retry the request after a short delay
2. If the error persists, contact support with:
   • The request_id from the response
   • Timestamp of the error
   • The operation you were attempting

INTERNAL_002: Database operation failed

Error Message: "Database operation failed"

HTTP Status: 500 Internal Server Error

Cause: An unexpected database error occurred while processing your request.

Remediation:

1. Retry the request after a short delay
2. If the error persists, contact support with the request ID
3. This is typically a transient issue

INTERNAL_003: External service error

Error Message: "An upstream service error occurred"

HTTP Status: 500 Internal Server Error. POST /v3/sender-profiles returns it with 502 Bad Gateway and the message "Could not verify this WhatsApp account with Meta" when the WhatsApp account in channels.whatsapp can't be verified because Meta couldn't be reached. Nothing is created.

Cause: An upstream service Sent depends on returned an error or couldn't be reached.

Remediation:

1. Wait a few moments and retry
2. Check API Status for known issues

INTERNAL_004: Timeout waiting for operation

Error Message: "Timeout waiting for operation"

HTTP Status: 504 Gateway Timeout

Cause: The operation timed out while waiting for an external service or internal processing.

Remediation:

1. The operation may still be in progress - check the resource status
2. Retry the request with the same idempotency key
3. Contact support if timeouts persist

INTERNAL_005: Service temporarily unavailable

Error Message: "Service temporarily unavailable"

HTTP Status: 503 Service Unavailable

Cause: The API is temporarily unavailable due to maintenance or high load.

Remediation:

1. Retry with exponential backoff
2. Check API Status
3. Wait for service restoration

Message Outcome Codes

These codes are never returned on an HTTP response. POST /v3/messages accepts the send with 202, and when the message ends FAILED, FILTERED or BLOCKED the code arrives as reason_code on GET /v3/messages/{id} (top level and on the event), on GET /v3/messages/{id}/activities, and on the message.failed, message.filtered and message.blocked webhooks. A cause with a code elsewhere in this catalog reuses it, so these cover only what a message outcome alone can have. Several carrier conditions fold into one code, so read reason for the likely causes.

Channel Status Reasons

These codes are never returned on an HTTP response. Every SMS market, WhatsApp account and RCS agent that isn't ACTIVE reports one as reason_code, with a sentence as reason. They appear on GET /v3/channels, the single-market reads, and Sender Profiles, and for SMS markets on the channel.* webhooks too. WhatsApp and RCS don't publish channel.* webhooks yet. The code is decided by the same logic as the status, so the two never disagree. On reads, an ACTIVE channel carries neither field. A channel.* webhook for an ACTIVE market omits reason_code but can still carry reason when the event brought its own explanation, such as a correction requested against a sender that still works.

Call Failure Reasons

These values are never returned on an HTTP response. A phone call that ends without completing reports why as failure_reason on GET /v3/calls/{id} and GET /v3/calls, and as reason on the call.failed webhook. The field is null on the read and omitted on the webhook when no reason was recorded, and always on a call that completed. The values are Sent's classification, never a carrier's own code.

Troubleshooting Guide

General Troubleshooting Steps

1. Check the Error Code: Use the error code to find its entry in this catalog
2. Review Request ID: Include meta.request_id when contacting support
3. Verify API Version: Ensure you're using v3 endpoints (/v3/)
4. Test in Sandbox Mode: Use sandbox: true to validate without side effects

Getting Help

If you can't resolve an error:

1. Documentation: Check this catalog and the Error Handling guide
2. Support email: support@sent.dm
3. Include in Support Request:
   • Request ID (meta.request_id)
   • Error code and message
   • Timestamp of occurrence
   • Endpoint and method
   • Request payload (sanitized)

Error Code Quick Reference

Every code documented on this page, in page order: