VALIDATION_ERROR | Request parameters or body failed validation. details is an array of { field, message, code }, one per rejected field. On POST /v1/projects/{id}/recipients and POST /v1/email/campaigns/{id}/recipients (422), details is one { field, reason } object naming why the phone number or email cannot be sent to. On triggered projects and campaigns and on follow-ups, the field is named in details: trigger.start and trigger.delay_minutes (a next-day start has no wait), scheduled_timezone, timezone and sequence_send_time (required with a next-day start or a follow-up that waits days), trigger.tag.tag_ids.<index> (not a manual tag of the organization), trigger (a started tag trigger’s tags cannot change), audience (required for a tag trigger’s first start, refused otherwise), reentry (any value but {"mode":"once"}), and follow_ups (at most 9 steps, waits of 1 to 365 days or 1 to 72 hours, text on every step, at least one stop rule, no follow-ups on a survey). |
INVALID_JSON | 400. The request body is not valid JSON (a trailing comma, an unquoted key, a cut-off body). Nothing was processed. |
PAYLOAD_TOO_LARGE | 413. The request body is larger than the size limit named in the message. Send less in one request, for example fewer rows per batch. |
UNSUPPORTED_CONTENT_TYPE | 415. The body uses a Content-Encoding or charset the API does not read. Send UTF-8, uncompressed or gzip-compressed. |
ORG_ACCESS_DENIED | Requested organization is not in your accessible hierarchy. |
ONBOARDING_INCOMPLETE | 403. The organization’s 14-day onboarding grace window has passed and the business profile or funding step (see Account Setup) is still incomplete. Returned on requests that create new resources: brands, campaigns, toll-free verifications, phone number purchases, email domains and senders, projects and project copies, and email campaigns and duplicates, including POST /v1/projects, POST /v1/projects/{id}/copy, and POST /v1/email/campaigns. details includes missingSteps (an array containing profile, funding, or both) and onboardingUrl (/onboarding). Nothing already running is affected, only new creates are blocked. |
ENTITLEMENT_REQUIRED | 403. The organization is not entitled to this feature; some features require enablement by Political Comms. Returned on every write (POST/PUT/PATCH/DELETE) under /v1/email/*, and on POST /v1/contact-lists/import with an email_column. details includes entitlement, the entitlement key that is missing (tendlc, toll_free, short_code, data_purchases, email, stripe_connect, phone_number_sharing, or sub_orgs). Contact support to request enablement. |
SENDING_PAUSED | 409. Sending is paused for the organization or platform-wide, by Political Comms. Returned on POST /v1/projects, POST /v1/projects/{id}/schedule, POST /v1/conversations/{id}/messages, POST /v1/email/campaigns/{id}/schedule, and POST /v1/email/campaigns/{id}/resume. details includes scope (organization or platform). |
MEDIA_NOT_USABLE | 400. A media_ids entry on POST /v1/conversations/{id}/messages is not in the conversation’s organization, is not ready, or belongs to a different brand than the project’s. Nothing was charged. |
RATE_LIMIT_EXCEEDED | Too many requests - wait for the Retry-After seconds before retrying. |
INVALID_STATE_TRANSITION | Project is not in a state that allows this operation. POST /v1/projects/{id}/schedule accepts ready and paused projects. |
NOT_A_SURVEY | The endpoint only applies to survey projects (type: survey). |
LIST_NOT_READY | Contact list must finish importing before it can be analyzed. |
ANALYSIS_NOT_COMPLETE | 409. GET /v1/contact-lists/{id}/download?type=analyzed was requested before analysis finished. Poll GET /v1/contact-lists/{id} until analysis.status is complete, or subscribe to the contact_list.analyzed webhook. |
LIST_ARCHIVED | 410. GET /v1/contact-lists/{id}, /download or /analyze named a contact list of your own whose contacts were removed 12 months after upload. A list that is not yours still returns 404. The list cannot be used again; upload the file again to create a new one. 409 on POST /v1/projects, the project update endpoint, or POST /v1/projects/{id}/schedule when such a list is named or already on the project: nothing is changed, and details.lists is an array of { id, name } for each one. Choose another list or upload the file again. A project that was already scheduled when its list was removed does not send: at its send time it moves from scheduled back to ready and your organization is notified. |
LIST_ANALYSIS_IN_PROGRESS | 409. POST /v1/projects, the project update endpoint, or POST /v1/projects/{id}/schedule referenced a contact list whose analysis is still running (analysis.status processing). Nothing is changed. details.lists is an array of { id, name, status } for each list still in analysis. Wait for analysis.status complete on GET /v1/contact-lists/{id} or the contact_list.analyzed webhook, then retry the same request. |
NO_SENDABLE_CONTACTS | 409. POST /v1/projects/{id}/schedule on a project whose contact lists hold no contact that can receive a text message (every row inactive, without a phone number, or a landline on an analyzed list). Nothing is changed. details.lists is an array of { id, name } for each list. Choose another list. When the lists do hold contacts but opt-outs or suppression lists remove every one, the schedule call succeeds and the project moves from compiling back to ready instead of scheduled or active. A scheduled project whose lists lose every sendable contact before its send time moves from scheduled back to ready the same way, with a notification. |
TAG_NAME_TAKEN | 409. POST /v1/tags, PATCH /v1/tags/{id}, or a list import with tag_names named a tag that already exists in the organization. Tag names are unique per organization, ignoring case. |
TAG_NOT_MANUAL | 400. The call needs a manual tag and the tag is an activity tag: renaming it, adding contacts to it or removing contacts from it, or naming it in tag_ids on a list import. An activity tag is named by its activity and has no members. |
TAG_IN_USE | 409. DELETE /v1/tags/{id} named a tag that a scheduled, compiling, active, sending, or paused project or email campaign uses. details.projects and details.emailCampaigns list up to 10 blocking sends each as { id, name, status }. Remove the tag from the send or wait for it to finish. A triggered project or email campaign that listens for the tag and is not completed, archived or deleted blocks it too, listed in details.triggeredItems as { id, name }: change or end it first. |
TAG_BUSY | 409. POST or DELETE /v1/tags/{id}/contacts, or POST or DELETE /v1/tags/contacts, named contacts an import is still writing. Retry in about a minute. |
LIST_NOT_FOUND | 404. contact_list_id on /v1/tags/{id}/contacts or /v1/tags/contacts is not a list of the tag’s organization. |
INSUFFICIENT_BALANCE | A wallet in the organization hierarchy cannot cover the scheduled send (422 on schedule) or the list analysis (402 on POST /v1/contact-lists/{id}/analyze, with nothing queued). This may be a parent organization rather than the one you called with - charges roll up, so every ancestor must cover its own share. details includes the shortfall plus organizationId and organizationName identifying which organization fell short, actingOrganizationId (the organization the call was made for) and isAncestor (true when the short wallet belongs to a parent of the acting organization). |
CONVERSATION_NOT_FOUND | 404. The conversation does not exist or belongs to an organization outside the key’s hierarchy; the two are indistinguishable by design. |
CONTACT_OPTED_OUT | 409. The contact replied STOP; a reply to this conversation is refused before any charge. Also returned by POST /v1/projects/{id}/recipients and the inbound hook when the phone number has opted out, and by POST /v1/email/campaigns/{id}/recipients when the address is suppressed. Final: do not retry. |
CONFLICT | 409. The resource is not in the right state for the call. On the triggered endpoints: POST /v1/projects/{id}/start, /end and /recipients (and the email /end and /recipients) on a project or campaign that is not triggered; a recipient added while the project or campaign is paused, never started or ended, which is refused rather than queued; end on one that was never started. Also PATCH /v1/projects/{id} when follow_ups changes after the project has started (“Follow-ups cannot be changed once the project has started. End it and copy it to change them.”). |
INVALID_PROJECT_TYPE | 400. type on POST /v1/projects must be broadcast, survey or triggered. |
CONVERSATION_NOT_SENDABLE | 409. The conversation has no sending number bound to it, so nothing can reply from it. |
PROJECT_DELETED | 409. The project behind the conversation was deleted. |
PHONE_NUMBER_UNAVAILABLE | 409. The conversation’s sending number was released or is inactive. |
SEND_ENQUEUE_FAILED | 503. A reply could not be handed to the delivery queue after billing; the charge was reversed and nothing was sent. Retry the same call. |
CARRIER_ESTIMATE_TIMEOUT | 503. The carrier throughput estimate for GET /v1/projects/{id}/throughput timed out and had no effect. Retry later. |
MIXED_PHONE_OWNERSHIP | 400. A project’s phone_number_ids mixed numbers the organization owns with numbers shared with it, or shared numbers from two different campaigns or registrations. Select numbers from one source. |
PHONE_SHARE_REVOKED | 409. A number the project selects was shared with the organization and the share has been revoked (or the number released). Choose a different number. |
IDEMPOTENCY_CONFLICT | The same Idempotency-Key is still processing - retry after the Retry-After seconds. |
IDEMPOTENCY_MISMATCH | An Idempotency-Key was reused with a different request body - that’s a client bug; use a fresh key for new requests. |
DATE_RANGE_TOO_LARGE | Date range exceeds the maximum allowed (31 days). |
DATE_TOO_OLD | Start date exceeds the look-back limit: 180 days for /messages/stats and /ledger/*, 90 days for /projects/stats. |
FUTURE_DATE_NOT_ALLOWED | Date range may not end in the future. |
INVALID_DATE_FORMAT | Date parameter must be in YYYY-MM-DD format. |