Errors

MALFORMED_REQUEST HTTP 400

The request could not be read. Send a JSON object with the header Content-Type: application/json.

details: reason (string, optional)

INVALID_HEADER HTTP 400

The :header header is not valid: :reason. Expected :expected.

details: header (string), reason (string), expected (string), received (string, optional)

LINE_CONTEXT_REQUIRED HTTP 400

A partner key must name the partner line it acts on with the MyComm-Line header (the line id).

INVALID_CURSOR HTTP 400

The cursor is expired, damaged or was issued for different filters. Restart the list without a cursor.

UNAUTHENTICATED HTTP 401

The API key is missing, unknown, revoked or expired. Send it as Authorization: Bearer <key>.

details: reason (string, optional)

WRONG_KEY_KIND HTTP 403

This kind of key cannot call this API. Use a :expected key.

details: expected (string)

ABILITY_MISSING HTTP 403

This key lacks the :required ability. Create a key that has it, or add it in the portal.

details: required (string)

IP_NOT_ALLOWED HTTP 403

Requests from :ip are not allowed for this key. Add the address to the key's allowed_ips or call from an allowed address.

details: ip (string)

LINE_CONTEXT_INVALID HTTP 403

The MyComm-Line header does not name a line this partner key can act on: the line belongs to another partner, was detached or does not exist. Check the line id.

PARTNER_ROUTE_NOT_ALLOWED HTTP 403

A partner key cannot call this endpoint. Partner keys send and read messages and conversations of their own line; the user manages channels, phones and settings.

ACCOUNT_SUSPENDED HTTP 403

This account is suspended and cannot use the API. Contact support to have it restored.

details: reason (string|null, optional), status (string, optional)

ACCOUNT_PENDING_DELETION HTTP 403

This account is scheduled for deletion and cannot use the API.

details: purge_at (string|null)

PARTNER_ACCESS_REVOKED HTTP 403

Partner access is not approved or was withdrawn for this key. Contact support.

NOT_FOUND HTTP 404

The resource does not exist, belongs to another account or is outside this key's scope. Check the id.

METHOD_NOT_ALLOWED HTTP 405

This method is not allowed on this path. See the endpoint list in the API reference.

IDEMPOTENCY_KEY_REUSED HTTP 409

This Idempotency-Key was already used with a different request. Use a new key for a new request.

IDEMPOTENCY_IN_PROGRESS HTTP 409

The first request with this Idempotency-Key is still running. Retry in a second.

REFERENCE_ID_EXISTS HTTP 409

A message with this reference_id already exists. Treat it as sent, or use a new reference_id to send it again.

details: message_id (string, optional), message (object, optional), reference_id (string, optional)

INVALID_STATE HTTP 409

This action is not allowed in the resource's current state.

details: status (string, optional), allowed_from (array, optional), used_by (array, optional)

NOT_CANCELLABLE HTTP 409

This message can no longer be cancelled because it is :status.

details: status (string)

NOT_RETRYABLE HTTP 409

Only failed or expired messages can be retried, and this one is :status.

details: status (string), failure_code (string|null, optional)

RETRY_LIMIT_REACHED HTTP 409

This message was already retried by hand :limit times. Send it again as a new message.

details: limit (integer)

NAME_TAKEN HTTP 409

That name is already used in this account. Choose another one.

details: field (string, optional)

IDENTITY_TAKEN HTTP 409

That address already belongs to another contact in this account. Update that contact instead.

details: contact_id (string, optional)

CHANNEL_ADDRESS_IN_USE HTTP 409

This number is already connected to another MyComm account. Disconnect it there first.

DEVICE_IN_USE HTTP 409

This phone is connected to another MyComm account or platform. Disconnect it there first, or contact support.

DECLINED_ON_DEVICE HTTP 409

The person holding the phone declined the request. Ask them to approve it and try again.

SIM_ALREADY_CONNECTED HTTP 409

This SIM is already connected to a channel in this account.

details: channel_id (string, optional)

PAYLOAD_TOO_LARGE HTTP 413

The request body is larger than the :max_bytes byte limit for this endpoint. Send less data per request.

details: max_bytes (integer)

VALIDATION_FAILED HTTP 422

The request has invalid fields. See details.fields for each field and the rule it broke.

details: fields (object)

INVALID_NUMBER HTTP 422

:input is not a valid phone number. Send it in international format, for example +923001234567.

details: input (string), reason (string, optional)

INVALID_ADDRESS HTTP 422

:input is not a valid address for this channel type.

details: input (string), channel_type (string, optional)

NOT_MOBILE HTTP 422

That number is valid but not a mobile number, so SMS cannot reach it.

details: input (string, optional), number_type (string, optional)

DESTINATION_NOT_ALLOWED HTTP 422

This channel may not send to that destination. Pick a recipient in an allowed country, or change the channel's allowed destinations.

details: country (string), reason (string, optional), allowed (array, optional)

BODY_TOO_LONG HTTP 422

The message text is too long to send. Shorten it.

details: segments (integer, optional), max_segments (integer, optional), characters (integer, optional), max_characters (integer, optional)

BODY_TOO_LONG_FOR_BULK HTTP 422

The message has :segments segments, more than the :max_segments allowed on the bulk lane for this country. Shorten it.

details: segments (integer), max_segments (integer)

BODY_EMPTY HTTP 422

The message has no text and no media after rendering. Send a body, a media item or a template that renders text.

CATEGORY_REQUIRED HTTP 422

Messages on the bulk lane and in batches need a category: transactional or marketing.

details: lane (string, optional), batch (boolean, optional), field (string, optional)

CATEGORY_MISMATCH HTTP 422

The content reads as promotional but was sent as transactional. Set the category to marketing or rewrite the text.

RECIPIENT_OPTED_OUT HTTP 422

The recipient :address opted out of marketing messages. Send it as transactional or remove the opt-out.

details: address (string), suppressed_at (string|null, optional)

MARKETING_NOT_ALLOWED HTTP 422

Marketing messages are not allowed for this country on MyComm because they get SIMs blocked. Send a transactional message instead.

details: country_iso (string, optional)

CONSENT_PROVENANCE_MISSING HTTP 422

This marketing message needs recorded consent for the recipient. Add the contact's consent source and send again.

details: address (string, optional), missing (integer, optional), total (integer, optional)

CONTENT_PROHIBITED HTTP 422

The text looks like impersonation or a scam, which carriers block. Rewrite it.

details: reason (string, optional), class (string, optional), terms (array, optional), host (string, optional)

SEND_AFTER_TOO_FAR HTTP 422

send_after is too far ahead. Schedule at most :max_days days out.

details: max_days (integer)

LINK_BLOCKED HTTP 422

The link :url points to a blocked domain. Remove or replace it.

details: url (string)

LINK_PUBLIC_SHORTENER HTTP 422

Public link shorteners get messages blocked. Send the full link and MyComm will shorten it.

details: url (string, optional)

TOO_MANY_LINKS HTTP 422

Bulk and campaign messages may hold only one link. Remove the others.

details: max (integer, optional)

CONTACT_BLOCKED HTTP 422

This contact's address is blocked in your account, so nothing can be sent to it. Unblock it first.

details: contact_identity_id (string)

CHANNEL_INACTIVE HTTP 422

Channel :channel_id is :status and cannot send. Reconnect it in the portal or send from another line.

details: channel_id (string), status (string)

LINE_ARCHIVED HTTP 422

Line :line_id is archived and cannot send. Unarchive it or send from another line.

details: line_id (string)

LINE_REQUIRED HTTP 422

Say which line sends this message: send line_id, channel_id or from, or use a key restricted to one line.

LINE_HAS_NO_SENDERS HTTP 422

Line :line_id has no channel to send through. Add a sender to the line, or name a channel with channel_id.

details: line_id (string)

LINE_IS_DIRECT HTTP 422

Line :line_id is the Direct line of the account. It holds every conversation no other line claims, so it cannot be archived.

details: line_id (string)

CHANNEL_LINE_MISMATCH HTTP 422

The sender fields point at different lines or channels. Send just one of line_id, channel_id or from.

details: line_id (string, optional), channel_id (string, optional), from (string, optional), channel_type (string, optional)

FROM_AMBIGUOUS HTTP 422

The from address matches channels of several types. Add channel_type to pick one.

details: channel_types (array)

CONTENT_CONFLICT HTTP 422

Send either content or the shorthand fields (body, media_ids, template_id, variables), not both.

details: fields (array, optional)

CHANNEL_CAPABILITY_UNSUPPORTED HTTP 422

This line's channel cannot carry that content or option. See details for what it supports.

details: channel_id (string, optional), channel_type (string, optional), capability (string, optional), supported_content_types (array, optional)

CHANNEL_CANNOT_INITIATE HTTP 422

This channel cannot start a conversation with that recipient. Wait for them to write first or use a channel that can.

details: channel_type (string, optional)

NO_IDENTITY_FOR_CHANNEL HTTP 422

The contact has no address this channel can send to. Add one, or send from a different channel.

details: contact_id (string), channel_id (string, optional), channel_type (string, optional)

CONVERSATION_WINDOW_CLOSED HTTP 422

The reply window for this conversation has closed. Send an approved template message instead.

details: window_closed_at (string, optional), allowed_content_types (array, optional)

IDENTITY_TYPE_UNAVAILABLE HTTP 422

That identity type is not available yet. Use a phone number.

details: type (string, optional)

CHANNEL_TYPE_NOT_ALLOWED HTTP 422

That channel type is not enabled for this account.

details: type (string, optional)

CHANNEL_TOKEN_INVALID HTTP 422

The provider rejected the channel token. Check it and connect again.

MEDIA_TYPE_UNSUPPORTED HTTP 422

This file type is not supported. Upload a JPEG, PNG, GIF or WebP image.

details: mime (string|null), accepted (array)

MEDIA_TOO_LARGE HTTP 422

The file is larger than the :max_bytes byte limit. Upload a smaller image.

details: size_bytes (integer, optional), max_bytes (integer)

MEDIA_COUNT_EXCEEDED HTTP 422

A message can carry at most :max media item. Send one media id.

details: max (integer)

MEDIA_NOT_FOUND HTTP 422

Media :media_id was not found or is already attached to another message. Upload the file again.

details: media_id (string)

TEMPLATE_INVALID HTTP 422

The template has a syntax error. See details for where.

details: position (integer, optional), message (string, optional)

TEMPLATE_ARCHIVED HTTP 422

This template is archived. Unarchive it or use another template.

FILTER_INVALID HTTP 422

The filter is not valid. See details for the part that is wrong.

details: pointer (string, optional), message (string, optional)

CONSENT_NOTE_REQUIRED HTTP 422

Removing an opt-out needs a consent_note that says how the person agreed to be messaged again.

CONSENT_ASSERTION_REQUIRED HTTP 422

Starting a marketing campaign needs compliance.consent_asserted set to true.

RISK_ACKNOWLEDGEMENT_REQUIRED HTTP 422

This sending rate is risky for the number. Set acknowledge_risk to true to apply it anyway.

details: risk (string), exceeds (object, optional)

ABOVE_PLATFORM_CEILING HTTP 422

A rate-policy value is above what this number may use. See details for the allowed ceiling.

details: field (string), value (integer), ceiling (integer), reason (string)

NEW_ACCOUNT_LIMIT HTTP 422

New accounts are limited during their first 14 days (limit :limit). Stay under the limit or wait.

details: limit (integer), recipients (integer, optional), devices (integer, optional)

ACCOUNT_THROTTLED HTTP 422

This account is throttled while MyComm reviews its sending. Marketing and new numbers are paused; contact support.

details: risk_state (string, optional)

ADDRESS_REQUIRED HTTP 422

This SIM does not report its number. Send the address (the phone number) to connect it.

COUNTRY_NOT_ENABLED HTTP 422

Numbers from this country are not enabled on MyComm yet.

details: country_iso (string, optional)

DEVICE_SIM_LIMIT HTTP 422

This device already carries the maximum number of SIMs allowed for its country. Use another device.

VERIFICATION_NOT_FOUND HTTP 404

No verification was found for this request. Start the verification again.

VERIFICATION_EXPIRED HTTP 410

The verification expired. Start it again.

VERIFICATION_LIMIT_REACHED HTTP 422

Too many verification attempts. Try again in :retry_after_seconds seconds.

details: retry_after_seconds (integer)

SIM_NOT_PRESENT HTTP 422

The phone no longer reports this SIM. Put the SIM back in the phone and try again.

DEVICE_NOT_ACTIVE HTTP 422

This device was disconnected. Pair it again before using it.

PAIRING_CODE_LIMIT_REACHED HTTP 429

Too many pairing codes. Try again in :retry_after_seconds seconds, or use one of the pending codes.

details: retry_after_seconds (integer)

CONNECT_SESSION_LIMIT_REACHED HTTP 422

Too many open connect sessions for this account. Finish or let some expire, then try again.

details: max (integer, optional)

PAIRING_CODE_EXPIRED HTTP 410

That pairing code expired. Create a new one.

SECOND_FACTOR_REQUIRED HTTP 403

This action needs the account owner to confirm a second factor (PIN, password, Google or an authenticator app) in the portal. API keys cannot do it.

details: reason (string)

BATCH_TOO_LARGE HTTP 422

A request holds at most :max items. Split it into smaller requests.

details: max (integer)

AUDIENCE_EMPTY HTTP 422

The campaign has nobody it can send to. Check the audience and its opt-outs.

details: skipped (object, optional)

RANGE_TOO_LARGE HTTP 422

The date range may span at most :max_days days. Ask for a shorter range.

details: max_days (integer)

UNSUPPORTED_MEDIA_TYPE HTTP 415

Send the body in the format this endpoint expects, with a matching Content-Type header (application/json for JSON endpoints).

details: header (string, optional), received (string|null, optional), expected (string, optional)

RATE_LIMITED HTTP 429

Too many requests. Wait for the time in the Retry-After header, then retry.

details: retry_after_seconds (integer, optional)

INTERNAL_ERROR HTTP 500

Something went wrong on our side. Retry with the same Idempotency-Key; if it keeps failing, quote the request_id to support.

SERVICE_UNAVAILABLE HTTP 503

The service is temporarily unavailable. Retry after the time in the Retry-After header.

details: reason (string, optional)