Error codes

What happened. The submitted role and group restrictions were refused because they would have removed an elevated capability from the admin submitting them. 'manage_tenant' is what admits an admin to changing these restrictions at all and 'view_credentials' is what admits one to rotating the tenant's Twilio credentials, so a write that excludes its own author from either leaves nobody able to undo it: the capability that would authorize the repair is the one the write removed.

What to do. Resend the write with the submitting admin's own Zendesk role and group included in the rule for every elevated capability it names -- or have an admin who will still be permitted afterwards submit it instead. Rules for 'app_use' and 'send' are not affected by this refusal; those remain reversible.

What happened. Zendesk authenticated this person, and the account they authorized with is not an administrator of this Zendesk account.

What to do. Ask an administrator of this Zendesk account to run the authorization step. Elevated operations are administrator-only by design.

What happened. This operation needs a server-attested admin session. The ZAF assertion identifies the installation, not the person, so it cannot grant elevated authority on its own.

What to do. Start an admin session from the app (POST /v1/sessions/admin/start), complete the Zendesk authorization, and present the returned session token on this request. Sessions are short-lived and are destroyed when the tenant uninstalls.

What happened. Whether this installation's role, group and per-number rules permit the signed-in Zendesk user could not be established: Zendesk did not answer. No rule was read, and nothing here says they are not permitted.

What to do. Retry. Do not change TextSend's role, group or per-number restrictions on the strength of this -- they were never read. If it persists, check Zendesk's status page and the tenant's Zendesk OAuth connection on the diagnostics page.

What happened. The signed-in Zendesk user is not permitted to perform this action in this installation: their Zendesk role or group is outside the restriction an admin configured, or the tenant's own Zendesk account did not vouch for the identity they claimed. Every refusal of that kind is reported identically, so a caller cannot tell which of them it met. A Zendesk that never answered is not one of them: that answers agent_authorization_unavailable instead, because it asserts nothing about this user.

What to do. Ask a Zendesk admin to add this role or group to TextSend's role and group restrictions, or perform the action from an admin account. If the action was expected to be permitted, reload the TextSend app inside Zendesk so it re-authenticates, then check that the tenant's Zendesk OAuth connection is still healthy on the diagnostics page.

What happened. Zendesk authenticated this person, and this Zendesk account's own TextSend configuration does not grant app use to their role or group.

What to do. Ask a TextSend administrator of this Zendesk account to include your role or group in the app-use restriction. Nothing is wrong with the Zendesk account itself -- this is the tenant's own policy.

What happened. Zendesk authenticated this person, and the account they authorized with is not a staff member of this Zendesk account in good standing.

What to do. Authorize with an active, unsuspended agent or administrator account of this Zendesk. End-user accounts cannot hold a staff session by design.

What happened. This operation records who performed it, and the ZAF assertion identifies the installation rather than the person. The agent id inside it is assembled by the app's own browser JS, so attributing a stored record to it would let any caller name a colleague.

What to do. Start a staff session from the app (POST /v1/sessions/agent/start), complete the Zendesk authorization, and present the returned session token on this request.

What happened. Whether this Zendesk account's app-use restriction admits this person could not be established: Zendesk did not answer. No restriction was read, and nothing here says they are excluded.

What to do. Try verifying again. Do not change the app-use restriction on the strength of this -- it was never read. If it persists, check Zendesk's status page.

What happened. TextSend withheld this recipient's answer: it was one a batch must never be given -- a refusal whose repair is safe only outside a batch, an error TextSend does not recognise, or a request only a single send may make. This is a fault in TextSend, not in the selection. Whether an earlier send of this batch may have reached them is shown beside it.

What to do. Send to this recipient on their own, from their ticket or their contact, and report this to TextSend support so the fault can be found.

What happened. This installation's subscription is unpaid, cancelled, or its 14-day trial has ended, so the install is read-only: sending, entering or replacing credentials, and number changes are refused. Nothing was sent and nothing was changed.

What to do. Renew or reactivate the TextSend subscription for this Zendesk account. Access is restored on the next nightly billing poll, not instantly on payment. Reading a ticket's message thread, viewing tenant diagnostics, disconnecting the stored Twilio credentials, and starting the uninstall/data-deletion flow all keep working while the install is read-only, and inbound customer messages are still received -- a read-only install stops sending, not receiving.

What happened. No billing state is recorded for this tenant, so whether the subscription is paid could not be determined. This gate fails closed, so the install is treated as read-only -- an unknown subscription is not a paid one.

What to do. This is an operations condition, not something an admin can fix from the app: the nightly billing poll has not yet recorded state for this tenant. Run the poll, or confirm it is scheduled and succeeding. Do not work around it by writing a billing row by hand -- the poll is the single writer.

What happened. The number's callbacks were read back from Twilio and do not match the URLs this installation serves, so inbound messages or delivery receipts would not reach it. The number was not activated.

What to do. Run the 'configure_webhooks' command for this number and activate again. If it fails a second time, something outside TextSend is rewriting the number's webhook configuration -- check for a Twilio Studio flow, a TwiML app, or a messaging service attached to the number.

What happened. The callback health check could not read the number's current configuration from Twilio, so it reached no verdict at all. The number was not activated, and nothing here says its callbacks are wrong.

What to do. Retry. Do not reconfigure the callbacks on the strength of this -- they were never inspected. If it persists, check Twilio's status page.

What happened. This customer's consent history holds a row this build cannot read, or is longer than one request can walk. The history is served whole or not at all (a partial consent record is indistinguishable from a complete one), so the read refuses rather than answering with part of it.

What to do. Do not treat the blank history as 'no decisions recorded' -- it is not one. Check the customer's consent state another way before sending, and report this to TextSend support: the row is in the tenant's consent records and the backend log names the tenant and the instant it was written.

What happened. The contact exists and their Zendesk profile records no phone number, so there is nowhere to send this message.

What to do. Add the customer's mobile number to their Zendesk user profile, then start the message again. TextSend reads the number from the profile rather than letting it be typed per message, so that every conversation with one person agrees on where its messages go.

What happened. TextSend could not read the contact's profile from Zendesk, so it never learned where this message would go. Nothing was sent and no ticket was created: acting on a destination that was never read is the one outcome worse than refusing.

What to do. Check Zendesk's status and TextSend's stored Zendesk credentials, then try again. A repeated failure with Zendesk healthy points at the OAuth grant rather than at this contact.

What happened. This Zendesk account holds no user record with the id the request named, so there is no profile to read an SMS destination from.

What to do. Open the contact in Zendesk and start the message from their user record again. A profile that was deleted or merged since the page loaded is the usual cause.

What happened. The contact has something recorded in their Zendesk phone field that is not a number this tenant can send to. Zendesk's phone field is free text, so it holds extensions, notes and instructions as often as it holds numbers, and a value that cannot be normalized is refused rather than passed on -- the send would fail later, reading to the agent as a broken send rather than as a profile to correct.

What to do. Correct the phone number on the contact's Zendesk profile. Write it in international form (a leading '+' and country code) or set this tenant's default country in TextSend's settings so national-format numbers can be normalized.

What happened. This account has more open conversations than the recipient picker can enumerate in one read, so the list it would show would be missing conversations without saying which. Nothing was read for the batch and nothing was sent.

What to do. Search the contacts source instead -- it names a person directly and does not walk the account's conversations. Conversations close on their own as their reply windows expire, so this also clears with time.

What happened. Whether this number belongs to the ticket could not be established: Zendesk did not answer. Nothing was compared, nothing was recorded or queued, and nothing here says the number is wrong.

What to do. Retry. Do not change the requester's phone number on the strength of this -- it was never read. If it persists, check Zendesk's status page.

What happened. The number this request names is not one of the ticket's customer numbers. TextSend acts from a ticket on the person that ticket is with -- its requester, or the customer on a conversation already under way there.

What to do. Open the ticket that is already having this conversation, or correct the requester's phone number on this ticket's Zendesk profile.

What happened. TextSend could not hand this attempt to its sending queue, so this attempt sent nothing.

What to do. Try sending again in a moment.

What happened. The requested capability is planned for a later release but is not built yet, so no plan grants it. This is a deliberate refusal that says why, not a plan or payment problem.

What to do. Nothing to repair -- the capability does not exist yet on any plan, including Pro. Upgrading the subscription will not enable it. Contact TextSend support to follow its progress.

What happened. This capability is part of the Pro plan; this account's plan is Starter. Nothing was changed, and saved templates are kept.

What to do. Upgrade the subscription to Pro.

What happened. More than one Zendesk user matched the inbound phone number.

What to do. Resolve the flagged identity-conflict ticket by choosing the correct Zendesk user.

What happened. The send under this idempotency key was already accepted, and the corrected Zendesk user on this retry is not the one recorded for the ticket's route, so the correction was not recorded. A ruling is written only once, over what Zendesk listed when the agent made it; it is never re-written under a spent key. Nothing was written and no second message was sent.

What to do. The earlier message was accepted without this Zendesk user correction, so the correction was not recorded and nothing new was sent. To record it, send the message as a new message carrying the corrected Zendesk user; a correction is recorded with the send that carries it.

What happened. This send would move the conversation to this ticket and also record an identity correction, and the correction can only be recorded against a conversation this ticket already holds. Nothing was sent, moved or recorded.

What to do. Send the message without the identity correction first, so the conversation moves here, then correct the identity.

What happened. The send carried a corrected Zendesk user, but Zendesk could not be searched for the customer's number, so the correction could not be recorded together with the evidence it was made over. Nothing was written and no message was sent.

What to do. Retry the send. A correction is only inheritable by later threads when it is recorded with what Zendesk listed at the time, so it is refused rather than saved half-formed while Zendesk is unreachable.

What happened. A corrected Zendesk user was submitted for a ticket that has no active route to the number pair on the request, so the correction had nowhere to be persisted. Nothing was written and no message was sent.

What to do. Send the correction from the ticket the SMS thread is actually routed to. A ticket loses its route once the route window closes (14 days by default) -- if the thread has expired, the next inbound message creates a new ticket to resolve identity on instead.

What happened. An agent-initiated send named a contact, but the number pair's active route carries a different identity decision, so the new thread's requester and the route's ruling would name different people.

What to do. Send from the contact the route was resolved to, or resolve the identity conflict on the existing thread first. Nothing was sent: opening the thread under the clicked contact would discard a decision an agent already made about this number.

What happened. The customer's phone number matched more Zendesk users than TextSend will read phone identities for, so at least one of those users was never classified and the number could not be shown to be theirs or shown not to be. Nothing was chosen, nothing was sent, and no ticket was filed under a matched identity.

What to do. Narrow what this number matches in Zendesk -- it is on the records of more users than one person can be reached at, and taking it off the records of the users who do not hold it is the fix. Until then, reply to the customer from the ticket instead of from this number. Retrying will not clear it: the same search returns the same users.

What happened. An inbound message was claimed for processing but never recorded the Zendesk ticket or comment it produced, so whether the customer's message already reached an agent is unknown.

What to do. Do not reprocess blind -- a second attempt risks a duplicate agent-visible note for one customer message, and no port method can ask Zendesk whether the first one landed. Look the MessageSid up in Twilio's console and in the tenant's routed Zendesk ticket, then either set the dedup row's status back to queued to allow one clean reprocess, or mark it processed. Do not delete the row -- a missing row is read as a data-integrity bug, not as a retry.

What happened. Two or more Zendesk tickets already carry the external id this submission's idempotency key computes, so TextSend cannot tell which thread the conversation belongs on and will not guess. Nothing was queued and no message was sent. This is not the search index lagging -- the tickets are there and there is more than one, which retrying does not change.

What to do. Your next Send starts a fresh conversation ticket. In Zendesk, merge or close the duplicate tickets for this contact so one thread remains.

What happened. An earlier attempt of this submission opened a Zendesk ticket for the conversation, and the customer's identity was disputed or settled before this attempt. That ticket is not filed the way the identity now requires, so TextSend did not move the conversation onto it. Nothing was queued and no message was sent. Retrying under the same idempotency key finds the same ticket and is refused again; a new key opens the conversation under the identity as it stands. The earlier ticket holds only TextSend's opening note.

What to do. The customer's identity changed while this conversation was being set up. Send the message again to start the conversation as it stands now. An empty TextSend ticket left by the first attempt can be closed.

What happened. The contact's previous ticket read as solved, and Zendesk closed it before TextSend could reopen it. A closed ticket takes no reply, so nothing was queued, no message was sent and no ticket was created.

What to do. The customer's previous ticket just closed. Send again to start a follow-up ticket.

What happened. Another submission is already starting a conversation with this contact on this number, and TextSend starts only one at a time so the two cannot become two separate threads. Nothing was queued and no message was sent.

What to do. Wait a few seconds, then send the same message again. By then the other send's conversation exists and this one joins it rather than opening a second.

What happened. The deployment's initiation signing key is missing, so TextSend cannot compute the key that makes a retried initiation adopt its ticket instead of creating a second one. Refused rather than sent without it: a send that worked would create a duplicate ticket on the agent's next retry, and nothing would say why.

What to do. Run TextSend's one-time provisioning step, which creates the key if it is absent and leaves an existing one untouched. A deployment that has never run it has no key; one that has should be checked for secret-store access.

What happened. TextSend could not set up the Zendesk ticket this conversation starts from, so nothing was queued and no message was sent. A ticket may have been created before the failure; it carries this submission's natural key, so a retry finds and adopts it once Zendesk's search index has caught up -- which is not immediate, and the repair action below says what that means for timing.

What to do. Wait a few seconds, then send the same message again -- not as a new message or a new batch, which would certainly start a second conversation. The retry finds the ticket the first attempt may have opened through Zendesk's search, which lags a new ticket briefly, so a retry within those seconds can still start a second one.

What happened. Zendesk refused to create or reopen the ticket this conversation continues on, so nothing was queued and no message was sent. Nothing was left half-built either: Zendesk rejected the request itself rather than failing partway through it, so there is no ticket for a retry to find.

What to do. Do not send it again yet; Zendesk refuses the same request the same way until the cause is fixed. Ask an administrator to check TextSend's Zendesk connection and the fields your account requires on a ticket -- a required custom field with no value is the usual cause.

What happened. Whether this account can hold another install attempt could not be established in time. Nothing was counted, nothing was written, and nothing here says the account is full.

What to do. Retry. If it persists, the install service is under unusual load; wait a moment before the next attempt.

What happened. Zendesk authenticated this person, and the account they authorized with is not an active, unsuspended administrator of this Zendesk account. Nothing was installed and no signing secret was issued or changed.

What to do. Ask an administrator of this Zendesk account to start again and authorize with their own account.

What happened. The submitted role and group restrictions could not be accepted. Either the request named neither dimension, or a value was not one this build can enforce -- a capability name must be one of the four this build knows, a role must be one Zendesk documents, an allowlist must be null (unrestricted) or a list of strings, and a per-number key must already be in E.164 form.

What to do. Resend with 'command' set to 'write_access_restrictions' and at least one of 'capabilities' (an object keyed by capability name, merged into the stored rules) or 'numbers' (an object keyed by E.164 sending number, which replaces the stored per-number rules wholesale). Each rule is an object with 'roles' and 'groups', either null for unrestricted or a list -- an empty list restricts to nobody. Credentials belong to the 'validate_credentials' command and are refused here.

What happened. The account subdomain was not a bare Zendesk subdomain. It must be a single label of letters, digits or interior hyphens, with no dots, scheme, port or path.

What to do. Enter only the first label of your Zendesk address, not the whole URL: for https://example.zendesk.com, enter 'example'.

What happened. The installation callback request did not match the expected shape.

What to do. Retry the install from Zendesk Admin Center.

What happened. The outbound message request did not match the expected shape: a missing or blank idempotency key, a missing or blank ticket id, a missing sender or recipient, or neither a body nor any media.

What to do. Resend with a non-blank idempotency key, the id of the ticket the send is being made from, both numbers in E.164 form, and at least one of a body or a media URL. Reuse the same idempotency key when retrying the same click -- that is what makes the retry return the existing operation instead of sending twice.

What happened. The multi-send submission could not be read as one. Nothing was sent, to any recipient.

What to do. Check that the request names a sending number, a message body, an idempotency key and at least one recipient reference, and submit it again. Recipient references come from TextSend's own recipient picker; a reference this backend did not mint names no record it can resolve.

What happened. The number-discovery request carried no recognised 'command' discriminator. Like the credential route, this route accepts one of a fixed set of commands, so that enabling a number carries no Twilio call and discovery carries no admin selection.

What to do. Resend with 'command' set to 'discover' (to re-read the account's numbers and their capabilities from Twilio), 'set_enabled' (to turn discovered numbers on or off), 'configure_webhooks' (to write an enabled number's inbound-message and delivery-status callback URLs into Twilio), or 'activate_number' (to health-check those callbacks and activate the number).

What happened. The number-enablement request did not match the expected shape: a missing or empty 'numbers' list, an entry missing its phone number or its enabled flag, a phone number that is not already in E.164 form, the same number named twice, or an unexpected field. Nothing was changed.

What to do. Resend with exactly 'command' and 'numbers', where 'numbers' is a non-empty list of {'phone_number': '+15551234567', 'enabled': true|false} entries, each number appearing at most once. The tenant comes from the authenticated session, so do not send one in the body.

What happened. The CSRF state parameter was missing, expired, already used, or did not match the pending install attempt.

What to do. Restart the install from Zendesk Admin Center.

What happened. The submitted revocation could not be accepted. Either the customer's number was unreadable, the reason was over its bound, or the body named a field this route does not take -- the actor and the timestamp come from the verified session and the server clock, and the scope is always tenant-wide.

What to do. Send only 'to' and an optional 'reason'. The reason is the agent's own note about the request, never the customer's message.

What happened. The phone number could not be normalized to E.164.

What to do. Correct the phone number, or set the tenant's default country.

What happened. The recipient list was asked for in a way this backend cannot answer: either the source was not one it offers, or the contact source was asked for without the text to search on. Nothing was read and nothing was sent.

What to do. Ask for source=conversations to list the conversations TextSend already routes, or source=contacts with a query naming who to look for. If this came from TextSend's own recipient picker rather than a direct API call, reload the app -- the picker builds this request itself and should never produce one the backend refuses.

What happened. The submitted template could not be accepted. Either it named no template to write, it named a field this command does not take, or a value was out of bounds -- a name must be non-blank and at most 80 characters, and a body must be non-blank and at most 1600 characters.

What to do. Resend with a 'name' and a 'body' that are both within those bounds. The tenant a template belongs to comes from the signed-in session and is refused in the body; credentials belong to the 'validate_credentials' command and are refused here.

What happened. The submitted template body contains a merge field this app cannot fill in, or a '{{' that is never closed. A template is stored with its placeholders intact and they are filled when an agent inserts it, so one that names something unresolvable would fail at the composer instead of here.

What to do. Use only these merge fields: agent.first_name, agent.name, requester.first_name, requester.name, ticket.id -- each written as {{requester.first_name}}. Any other '{{' must be removed.

What happened. The submitted tenant configuration could not be accepted. Either it named no setting to change, it named something this route does not configure, or a value was not one TextSend allows -- a default country must be a two-letter upper-case region code, the reopen behaviour must be one this build knows, the identity-conflict placeholder must be a Zendesk user id, and the multi-send limits must sit inside the product's own bounds.

What to do. Resend with 'command' set to 'write_settings' and at least one of 'default_country' (a region code such as 'US', or null to clear it), 'reopen_behavior', 'include_secondary_phone_fields', 'identity_conflict_requester_id' (a Zendesk user id, or null to hand conflict tickets back to TextSend's own user), 'quiet_hours', 'quiet_hours_override_allowed', 'multi_send_max_recipients' (0 to switch multi-send off, at most 25) or 'multi_send_min_interval_seconds' (at least 60). The multi-send bounds are product limits rather than defaults and cannot be raised. Credentials belong to the 'validate_credentials' command and are refused here.

What happened. The Twilio configuration request carried no recognised 'command' discriminator. This route accepts one of a fixed set of commands, so that a settings-only write carries no credentials at all.

What to do. Resend with 'command' set to 'validate_credentials' (to submit or rotate Twilio credentials), 'write_settings' (to change tenant configuration), 'write_access_restrictions' (to change which roles, groups and sending numbers agents may use), 'create_template', 'update_template' or 'delete_template' (to change the saved SMS templates agents insert), or 'disconnect_credentials' (to delete the stored Twilio credentials).

What happened. The submitted Twilio credentials were missing, blank, carried an unexpected field, or were not the shape Twilio issues. No call was made to Twilio and nothing was stored.

What to do. Resend with exactly 'command', 'account_sid', and 'auth_token'. The Account SID is 'AC' followed by 32 hexadecimal characters and the auth token is 32 hexadecimal characters -- if both look right, check they have not been pasted into each other's field. The tenant comes from the authenticated session, so do not send one in the body.

What happened. The disconnect request carried a field other than 'command'. Nothing was deleted.

What to do. Resend with exactly {'command': 'disconnect_credentials'}. The tenant comes from the authenticated session, and no credential is needed to remove the stored ones.

What happened. The stored role and group restrictions for this installation could not be read. Nothing is authorized while they are unreadable: an unreadable restriction is never treated as an absent one.

What to do. Re-save the role and group restrictions from TextSend's settings to rewrite the stored value. Until then every agent-facing request for this installation is refused, which is deliberate -- the alternative would be authorizing against a configuration nobody can read.

What happened. The stored configuration for this tenant could not be read. It is not treated as an absent one: an unreadable value would otherwise turn a configured 'require a new ticket' back into a reopen, and a configured default country back into refusing every number that is not already E.164.

What to do. Re-save the tenant configuration from TextSend's settings to rewrite the stored value. Until then routing and normalization refuse to act for this tenant rather than acting on a configuration nobody can read.

What happened. This Zendesk account authorizes the app with its own OAuth client, and the service does not hold that client's secret, so the authorization could not be completed. Nothing was changed.

What to do. Nothing on your side can fix this. Report it to support: an operator enters this account's OAuth client secret in the operator console, and then you can start again.

What happened. This Zendesk account authorizes the app with its own OAuth client, and the service could not read that client's secret just now, so the authorization could not be completed. Nothing was changed.

What to do. Start again in a few minutes. If it persists, report it to support: the service that holds the secret is not answering.

What happened. This account's multi-send recipient cap is zero, which turns multi-send off. Nothing was sent, to any recipient. Single sends are unaffected.

What to do. An administrator can raise the cap in TextSend's settings, up to the product ceiling. Until then, send to each recipient from their own conversation.

What happened. This account dispatched a multi-send batch too recently. Nothing was sent, to any recipient. The interval between batches is one of the two limits TextSend places on this feature, and it is what keeps a guarded transactional multi-send from behaving like a campaign sender.

What to do. Wait the number of seconds the response names and submit the batch again. The wait is the account's own configured interval, which an administrator can lengthen but not shorten below the product floor, in TextSend's settings. Single sends are unaffected and keep working throughout.

What happened. No multi-send run with this id exists for this account. Either the id was not one this backend returned, or the run is older than the retention window and was deleted with its receipts.

What to do. Look at the recipients' tickets to see what was sent: every message a batch sends is recorded on its ticket. Submitting the same batch again answers each recipient it already reached as sent, without sending twice.

What happened. The batch ran out of time before it reached this recipient, so this send of it sent them nothing. An earlier send of the same batch may already have; the entry's may_have_gone says so. A batch is dispatched within a fixed time so that it always finishes inside the window its queue message is leased for; when Zendesk answers slowly, the recipients left at the end are the ones that do not fit.

What to do. Send the same batch again. Every recipient it already reached answers as sent without a second message, so a resend only dispatches the ones left over.

What happened. The callback health check passed but the activation could not be recorded, so the number is not active. Its callbacks at Twilio are correctly configured.

What to do. Retry the activation. The Twilio side needs no repair -- the failure is in this system's operational storage.

What happened. Twilio refused an authenticated call made with this tenant's stored credentials, so they are no longer valid for that account. No number record was changed.

What to do. Re-submit the Account SID and auth token for the account the numbers belong to. A token rotated at Twilio stops working immediately, and the stored copy must be replaced before discovery can run.

What happened. The account's numbers could not be read: Twilio did not answer, or answered with a failure that says nothing about the credentials themselves. No number record was changed, and every number already known stays exactly as it was.

What to do. Retry. This is not a signal to rotate anything -- the stored credentials were never judged. If it persists, check Twilio's status page before changing them.

What happened. The sending number is disabled or lacks the required capability.

What to do. Enable the number, or choose a capable number in tenant settings.

What happened. This account has more sending numbers enabled than its subscription plan allows (Starter allows 2, Pro allows 15), and this number is beyond that allowance: enabled numbers count in the order they were activated, oldest first, and a number not activated since it was last enabled counts last. Nothing was sent. The number keeps receiving inbound messages.

What to do. Disable sending numbers in TextSend's Settings until no more are enabled than the plan allows, or upgrade the subscription to Pro. Until then, choose a sending number within the allowance.

What happened. Zendesk rejected the OAuth authorization code exchange.

What to do. Restart the install from Zendesk Admin Center.

What happened. The destination number has opted out of messages from this tenant.

What to do. Ask the customer to reply START to resume messages, or reach them through another channel.

What happened. A file attached to an outgoing text message is not a type Twilio will send as MMS, so the message was not sent.

What to do. Retrying cannot help -- the file is what it is. Zendesk decides an upload's type from its contents rather than from the name or the label the composer sent, so a file it stored as an unrecognised type needs re-exporting as JPEG, PNG or GIF. The attachments are already on the ticket and are not resent.

What happened. The files attached to an outgoing text message could not be moved into Zendesk, so the message was not sent. Nothing reached the customer.

What to do. The send is unclaimed and the queue will retry it. The attachments never came to rest on this server, so nothing needs cleaning up here. If it keeps failing, check the tenant's Zendesk OAuth token and that the sending ticket still exists.

What happened. The message was handed to Twilio, but the route binding the customer's number pair to the sending ticket could not be written, so a reply would not find the thread it belongs to.

What to do. The operation carries the Twilio message SID and no transcript note id, which is the repairable state -- the next delivery of the queue message writes the missing route and the missing note together without sending again. Do not resend the message. If it is still failing after the queue's retry budget, the fault is in this system's operational storage, not in Twilio or Zendesk.

What happened. This message was accepted but no outbound worker picked it up before its place in the queue ran out. Nothing was sent to the carrier and nothing will send it later.

What to do. Send the message again. If sends keep expiring, an admin should check that the outbound worker is running: messages only expire when nothing is reading the queue.

What happened. An outbound operation was claimed for sending but never recorded a Twilio message SID, so whether the message actually went out is unknown.

What to do. Do not resend blind: the request may have reached Twilio and its SID never been recorded, so a resend risks a duplicate the customer sees. Nothing will settle this row on its own either -- reconciliation settles a row by asking Twilio about its SID and skips the rows that have none, and this status is terminal, so no retry is coming. An admin has to recover the outcome by hand in the Twilio console: match this row's masked sending number against the account's own number list, filter the message log to that number, and read a window around this row's timestamp -- a row with no SID has no send time, so that timestamp is when the message was submitted, not when it was tried. What turns up decides whether to send it again.

What happened. This message was accepted, but by the time the outbound worker dispatched it the tenant had no usable Twilio credentials stored -- the Twilio account was disconnected, a credential write or disconnect did not finish, or a stored value is blank or malformed. Nothing was sent to the carrier and the send will not be retried.

What to do. An admin needs to open Settings, enter the Account SID and auth token under Twilio account, and press Connect Twilio account; the credential row in the tenant diagnostics panel says which of the three it was. Send the message again afterwards: this one is terminal, so nothing will deliver it later.

What happened. This message was accepted while the install could send, but by the time the outbound worker dispatched it the install had become read-only -- its subscription is unpaid, cancelled or out of trial, or no billing state could be read for it at all. Nothing was sent to the carrier and the send will not be retried.

What to do. An admin needs to restore the subscription, or -- if the tenant diagnostics panel reports no billing state at all -- run the nightly billing poll. Access returns on the next poll, not instantly on payment. Send the message again afterwards: this one is terminal, so nothing will deliver it later.

What happened. The tenant's plan is unknown, null, or does not include this capability.

What to do. Confirm the subscription plan and retry, or contact support.

What happened. The message was not sent because it would start a new conversation during the tenant's configured quiet hours.

What to do. Once the quiet-hours window ends, send it again, or ask an administrator to change the window. If this account lets agents send during quiet hours, sending it again will offer you the option to confirm.

What happened. The send under this idempotency key was already accepted without a quiet-hours override, so the override on this submission was not recorded. An override is written with the send it authorizes and never re-written under a spent key, for the reason a corrected identity is not: it would attribute a decision to an agent after the fact. The accepted send is still held at the quiet-hours gate, so reporting it as already sent would be wrong as well. Nothing was written.

What to do. The earlier message was accepted without a quiet-hours acknowledgement and is waiting for quiet hours to end. This acknowledgement was not added to it, and nothing new was sent. Check the ticket's conversation history for how it goes.

What happened. The message would start a new conversation during the tenant's configured quiet hours. This tenant allows agents to send anyway once they confirm.

What to do. Confirm the send to deliver it now, which is recorded, or wait until the quiet-hours window ends.

What happened. Another recipient in this batch has the same phone number, and this message may already have gone to it -- it was queued for that number by this send or an earlier send of the same batch -- so this one was not sent a second copy.

What to do. Nothing needs doing -- the message goes to that number once. Two entries in a batch can share a number without the picker being able to tell: a conversation and a contact can, and so can two conversations on different sending numbers, and the picker never holds a number to compare. Drop one of the two from the selection to keep the list tidy.

What happened. An earlier submission of this page was accepted. If no page showed you a new secret, start a new recovery.

What to do. Paste the secret the earlier submission showed into the app's signing secret setting. If none was shown, or it was not copied, start a new signing-secret recovery at /v1/installations/zendesk/rekey/start?subdomain= followed by your Zendesk subdomain, on the app's backend host.

What happened. Zendesk did not confirm it revoked the one-time authorization this recovery used, so the signing secret was not replaced. The current secret still works.

What to do. Start the signing-secret recovery again in a few minutes.

What happened. This confirmation is not one the recovery is waiting for in this browser: it expired, it came from another page or browser, or it was already used. This request replaced nothing.

What to do. If the app is refused, start the signing-secret recovery again and confirm on the page it shows within five minutes.

What happened. This Zendesk account has no completed installation of this app, so there is no signing secret to replace. Nothing was changed.

What to do. Install the app from Zendesk Admin Center. The install shows the signing secret.

What happened. The ticket's requester exists and their Zendesk profile records no phone number, so this ticket has no SMS destination.

What to do. Add the customer's mobile number to their Zendesk user profile, then reopen the TextSend app. TextSend deliberately reads the number from the profile rather than letting it be typed per message, so that every ticket for one person agrees on where its messages go.

What happened. TextSend could not read this ticket's requester from Zendesk, so it never learned where this message would go. Nothing was sent to this recipient.

What to do. Check Zendesk's status and TextSend's stored Zendesk credentials, then send the same batch again: the recipients it already reached are not sent a second copy.

What happened. The ticket's requester has something recorded in their Zendesk phone field that is not a phone number this tenant can send to. Zendesk's phone field is free text, so it holds extensions, notes and instructions as often as it holds numbers, and a value that cannot be normalized is refused rather than passed on -- the send would fail later, reading to the agent as a broken send rather than as a profile to correct.

What to do. Correct the phone number on the requester's Zendesk profile. Write it in international form (a leading '+' and country code) or set this tenant's default country in TextSend's settings so national-format numbers can be normalized.

What happened. An agent-initiated send named a contact whose number pair already has more than one active route, so there is no single ticket the message belongs on.

What to do. Open the ticket this message belongs to and send from there. Nothing was sent: picking one of the live threads on the agent's behalf is what would split the conversation.

What happened. The conversation was moved to the sending ticket, but the private note saying so could not be written to one of the two tickets.

What to do. The operation records which move notes were written, and the next delivery of the queue message writes only the missing one without sending again. If it is still failing after the queue's retry budget, check the tenant's Zendesk connection.

What happened. Moving this conversation here would put two answers to who the customer is on one ticket: the conversation carries an agent's identity decision naming a different person than this ticket's requester, or the customer's identity is in dispute. Nothing was sent and the conversation was not moved.

What to do. Resolve the identity conflict on the ticket that holds the conversation first, or start a new conversation from the customer's contact.

What happened. Send anyway was asked for, and this conversation cannot be moved here: moving conversations is turned off for this account, more than one conversation with this customer is live, or the status of the ticket that holds it could not be read. Nothing was sent and the conversation was not moved.

What to do. Open the ticket that holds the conversation and reply there. If its status could not be read, try again in a moment.

What happened. A second ticket attempted to send to a number pair that already has an active route from a different ticket.

What to do. Continue from the ticket that holds the conversation.

What happened. The send under this idempotency key was already accepted with a different message: its text or its attachments differ from this submission's. Answering it as a duplicate would report this message as sent when the one accepted earlier is what goes out. Nothing was written and no message was sent.

What to do. The earlier message was accepted, and this edited version was not sent. To send it too, send it as a new message.

What happened. The send under this idempotency key was already accepted, and it went to a different contact than this submission names. A spent key is answered as a duplicate only for the send that spent it: answering this one that way would report a message to one contact as though it had been sent to another, and adopting that send's thread would put this message in front of the wrong customer. Nothing was written and no message was sent.

What to do. The earlier message was accepted for a different contact, and this one was not sent. To send it to this contact, send it as a new message.

What happened. The send under this idempotency key was already accepted carrying a different number of attachments than this submission does. Answering it as a duplicate would discard the difference silently: the attachments on this submission would never be uploaded, never be sent, and never appear on the ticket, while the response said the message had gone. Nothing was written and no message was sent.

What to do. The earlier message was accepted with different attachments, and this one was not sent. To send it with these attachments, send it as a new message.

What happened. The send under this idempotency key was already accepted, and it went out from a different connected number than this submission chose. The conversation belongs to the pair of numbers, not to the destination alone: answering this submission as a duplicate would report a thread under one of the tenant's numbers as though it were under another, and on a new conversation it would hand back a thread the agent did not choose the sender for. Nothing was written and no message was sent.

What to do. The earlier message was accepted from a different number, and this one was not sent. To send it from this number, send it as a new message.

What happened. The send under this idempotency key was already accepted onto a different ticket than this submission names. One customer can have several tickets, so this is an ordinary mistake rather than an attack -- but answering it as a duplicate would put the transcript note on the first ticket while telling the agent watching this one that their message went out. Nothing was written and no message was sent.

What to do. The earlier message was accepted on a different ticket, and this one was not sent. To send it from this ticket, send it as a new message.

What happened. The send under this idempotency key was already accepted, and it did not move the conversation from the ticket this submission names. Answering it as a duplicate would report a move that never happened. Nothing was written, moved or sent.

What to do. The earlier message was accepted without the move this one asks for, and this one was not sent. If the conversation should still move to this ticket, send it as a new message.

What happened. TextSend could not finish accepting this message, so nothing was sent. The conversation had already moved to this ticket and could not be put back.

What to do. The customer's replies now come to this ticket, or to the ticket the error names when another send moved the conversation on since. Try sending again from here, and tell whoever works the ticket that held the conversation, because it has no note about the move.

What happened. TextSend could not finish accepting this message, so nothing was sent. The conversation was put back on the ticket that held it.

What to do. Nothing moved. Try sending again in a moment.

What happened. This TextSend deployment is not configured for this feature yet, so the request was refused before anything was changed.

What to do. Nothing on your side can fix this. Try again later, and if it keeps happening, report it to TextSend support: the backend log names the setting that is not set.

What happened. Whether this installation can hold another pending session authorization could not be established in time. Nothing was counted, nothing was written, and nothing here says the installation is at its limit.

What to do. Retry. If it persists, the service is under unusual load; wait a moment before the next attempt.

What happened. The submitted template is nothing but a phone number, or nothing but a link. TextSend keeps whole phone numbers and full URLs out of stored records, and that rule applies to a template's own text as it does everywhere else.

What to do. Write the template as the sentence the customer should receive. A number or a link inside a sentence is kept as written -- it is a value that is *only* a number or *only* a link that cannot be stored.

What happened. This template was changed by someone else after it was opened for editing, so the submitted version was not written. Saving it would have discarded their change with no trace of it.

What to do. Reload the template to see the current text, then reapply the edit and save again.

What happened. This tenant already holds the maximum number of saved templates, so the submitted one was not created. Nothing was overwritten to make room.

What to do. Delete a template that is no longer used, then create this one again.

What happened. No template with that id exists for this tenant. It was either deleted by another administrator or never created.

What to do. Reload the template list. If it is gone, create it again; the id of a deleted template is never reissued.

What happened. This template is stored in a form this build can no longer read back, so it was not rewritten. An edit needs the parts of the row that could not be read, and inventing them would not be an edit of what is stored.

What to do. Delete this template and create it again. It is listed as unreadable, and deleting it does not require reading it.

What happened. This Zendesk account already has a completed installation of this app.

What to do. Installing again is not needed. If the signing secret is lost or does not match, an administrator can replace the signing secret for this Zendesk account instead, which keeps the account's data.

What happened. No installation is bound to this tenant id.

What to do. This indicates a data-integrity problem, not an end-user error -- confirm the tenant id was not corrupted in transit and that its installation was not deleted out from under an in-flight message.

What happened. Processing was revoked, but at least one stored credential could not be deleted, so the uninstall is not complete.

What to do. Retry the uninstall. If it keeps failing, contact support -- the surviving credential names are in the operator telemetry for this request, so support can finish deleting them from the secret store.

What happened. Sending is paused for this account by TextSend support. Nothing was sent.

What to do. Contact TextSend support; once support lifts the pause, send it again.

What happened. This tenant's account has been deleted. Processing stopped when the deletion started: usually about a week (7-8 days) after the app was removed and always within 30 days of removal, or at once when the account was deleted on request. Its remaining metadata is purged within 30 days after deletion started.

What to do. Install the app again from Zendesk Admin Center. A new installation is issued a new tenant id; the deleted one is never reactivated.

What happened. This ticket's message index holds a row this build cannot read -- one that names no source row, or one whose recorded time names no instant. Whether the conversation is live cannot be decided from it, and the quiet-hours window is decided on that answer, so the send refuses rather than guessing which way.

What to do. Nothing was sent and nothing was recorded against this ticket; a retry runs the same read and will refuse the same way until the row is repaired. Report this to TextSend support -- the row is in this ticket's message index and the backend log names its key.

What happened. Zendesk refused TextSend's read of the thread this contact already has, so TextSend could not tell whether the message belongs on that thread or on a new one. Nothing was sent and nothing was created. Zendesk answered, and its answer was a refusal -- this is not the vendor being unreachable.

What to do. Do not retry; the read is refused the same way every time. Ask an administrator to check TextSend's Zendesk connection on the settings page -- this is the app's own access to that ticket, not yours.

What happened. TextSend could not read the status of the thread this contact already has, so it could not tell whether the message belongs on that thread or on a new one. Nothing was sent and nothing was created: guessing the status would put the message on the wrong thread, or start a second one beside a live conversation.

What to do. Check Zendesk's status, then send the same message again. TextSend decides the thread afresh on each attempt, so once Zendesk can be read the retry settles it.

What happened. Zendesk reported a status for this contact's existing thread that TextSend does not recognise, so it could not tell whether the message belongs on that thread or on a new one. Nothing was sent and nothing was created. This is not Zendesk being unreachable -- the read succeeded and the answer was a value outside the documented set, which is the same on every attempt.

What to do. Do not retry; the read will return the same unrecognised status. Report this to TextSend support with the ticket's current status as Zendesk shows it -- TextSend has to learn the value before this thread can be used. In the meantime the contact can be replied to from the ticket in Zendesk directly.

What happened. The ticket exists and names no requester, so there is nobody for TextSend to read a destination number from. It is refused rather than answered with an empty destination: a composer told the destination is empty cannot tell that apart from a requester whose phone field is blank, and the two are repaired differently.

What to do. Set the ticket's requester in Zendesk to the person this conversation is with, then reopen the TextSend app.

What happened. The ticket names a requester this Zendesk account no longer holds a user record for -- typically a profile that was deleted or merged into another after the ticket was raised.

What to do. Reassign the ticket's requester in Zendesk to the surviving user profile. Until then TextSend has no profile to read a number from and will not guess one.

What happened. This installation already has the maximum number of session authorizations waiting to be finished.

What to do. Close the authorization windows already open for this app, or wait ten minutes for the earlier attempts to expire and try again. If it persists past that with nothing else open, tell an administrator: something is starting authorizations in a loop.

What happened. The batch named more recipients than this account's multi-send cap allows. Nothing was sent, to any recipient -- the cap is a property of the batch, so the honest answer is to refuse the batch rather than to send to the first few and drop the rest.

What to do. Remove recipients until the batch is within the cap and submit it again, or ask an administrator to raise the cap in TextSend's settings. The cap cannot be raised above the product ceiling, which is not configurable.

What happened. The message was handed to Twilio, but the private transcript note recording it could not be written to Zendesk, so the ticket has no record of the send.

What to do. The operation carries the Twilio message SID and no transcript note id, which is the repairable state -- the next delivery of the queue message writes the missing note without sending again. Do not resend the message. If the note is still missing after the queue's retry budget, check the tenant's Zendesk OAuth token and that the ticket still exists.

What happened. The server-held key that signs transcript references is not readable, so the thread cannot name the media items its messages carried. The thread is refused rather than served without them: media counts with no references read exactly like a conversation that carried no media.

What to do. This is a deployment-level configuration gap, not an end-user error -- provision the transcript-reference signing key in the secret store and retry. No message, note, or delivery state is affected while it is missing.

What happened. Deleting the stored Twilio auth token failed, so nothing was deleted. The stored credentials are untouched and still in use.

What to do. Retry the disconnect. The failure is in this system's secret storage; if it repeats, check the secret store's availability and the backend's permissions on it.

What happened. The stored Twilio auth token was deleted but its account SID was not. Sending and inbound webhook validation have already stopped for this tenant; only the account SID, an identifier, remains stored.

What to do. Disconnect again to finish removing the pair -- deleting what is already gone is safe. To reconnect instead, enter the Account SID and auth token under Settings, Twilio account, and press Connect Twilio account, which stores the pair afresh.

What happened. Twilio accepted the submitted credentials but storing them failed, so nothing was written. Any previously stored credentials are untouched and still in use.

What to do. Retry the submission. The credentials are known good -- the failure is in this system's secret storage, not on the Twilio side, so contact support if it repeats rather than changing them.

What happened. The Twilio auth token was stored but its account SID was not, so the stored pair is mismatched. This tenant can neither send nor validate inbound webhooks until both halves are written together.

What to do. Re-submit the same Account SID and auth token immediately -- this repairs the pair. Sending is broken for this tenant until it succeeds; treat it as an outage, not as a failed configuration change.

What happened. Twilio refused an authenticated call made with the submitted credentials, so they are well-formed but not valid for that account. Nothing was stored, and any previously stored credentials are untouched.

What to do. Copy the Account SID and auth token again from the Twilio console for the account the numbers belong to. If the auth token was recently rotated at Twilio, the previous value stops working immediately and the new one must be submitted here.

What happened. Twilio rejected this tenant's stored Account SID and Auth Token on several consecutive sends, so TextSend has suspended sending with them. Nothing was sent. Deliberately a different condition from an unpaid install: the subscription is not in question here.

What to do. Re-enter the Twilio Account SID and Auth Token in TextSend's Twilio settings. Sending resumes as soon as Twilio accepts the submitted pair -- there is no wait and no separate reset, and a send Twilio accepts clears the suspension too. Receiving inbound messages, reading a ticket's thread, and viewing tenant diagnostics all keep working while sending is suspended.

What happened. This tenant has no usable Twilio credentials stored, so there is no account whose numbers could be read or sent from. This is a configuration gap, not an outage.

What to do. Open TextSend from the icon in the left sidebar of the agent interface, go to Settings, enter the Account SID and auth token under Twilio account, and press Connect Twilio account. TextSend checks the pair with Twilio and stores it. Then run number discovery.

What happened. The Twilio account these credentials belong to owns no incoming number matching the one this tenant has on record, so there was nothing to configure.

What to do. Re-run number discovery and choose a number from the result. If the number was released or moved to another Twilio subaccount, it can no longer be configured here.

What happened. The credential check could not reach a verdict: Twilio did not answer, or answered with a failure that says nothing about the credentials themselves. Nothing was stored, and any previously stored credentials are untouched.

What to do. Retry. This is not a signal to rotate anything -- the submitted credentials were never judged. If it persists, check Twilio's status page before changing them.

What happened. The request named a number this tenant has never discovered, so TextSend holds no record of what that number can do. Nothing was changed -- not even for the numbers in the same request that are known.

What to do. Run number discovery first. If the number still does not appear, confirm it belongs to the Twilio account whose credentials this tenant submitted, and that Twilio reports it as SMS- or MMS-capable -- a voice-only number is never a sender.

What happened. This Zendesk account holds no ticket with the requested id. Nothing was read and nothing was written.

What to do. Open the TextSend app from a ticket that still exists. A ticket that was deleted or merged away keeps its id in an open browser tab long after Zendesk stops answering for it, so reloading the tab is usually the whole fix.

What happened. Twilio did not accept the callback-URL write, and answered with a failure that says nothing about the number itself. The number's callbacks are unchanged.

What to do. Retry. This is not a signal that the number or the credentials are wrong -- neither was judged. If it persists, check Twilio's status page.

What happened. This Zendesk account runs its own copy of the TextSend app, and TextSend has not been told that copy's app id, so it has nowhere safe to deliver the session. Nothing was changed.

What to do. Nothing on your side can fix this. Report it to TextSend support: an operator enters this account's private app id in the TextSend console, and then you can try again.