Error Handling

We give you two layers of visibility into message failures:

Unified error codes (errorCode): standardized categories we manage.
DCA status block (dcaStatus): raw, detailed status passed directly from the DCA (downstream carrier aggregator).

The dcaStatus object

The dcaStatus object is meant for deep-dive debugging. It contains the exact response we received from the upstream provider.

Field	Description
`providerId`	Abstract provider identifier
`code`	Provider-specific status or error code
`name`	Provider-specific symbolic status or error name
`description`	Human-readable description from the provider

Usage guidelines

Use errorCode for application logic, error grouping, alerting, and user-facing handling.

Use dcaStatus for troubleshooting and provider-specific diagnostics.

Note: Provider-specific codes and descriptions pass through from the DCA as-is. Don't treat them as a stable public taxonomy, since providers can change them.

Provider-specific error examples

When errorCode points to a provider-level issue, use dcaStatus.providerId and dcaStatus.code together to identify the root cause. These are examples of provider-specific codes returned by DCAs.

dcaStatus.providerId = 1

Code	Description
15	Screening blocked the message
488	Spam reject: unverified TFN
1007	Destination address doesn't accept messages from toll-free numbers
1206	Destination number can't currently receive text messages (no reception, or the handset is off). Check with the end user.
1116	Destination number isn't text-enabled

dcaStatus.providerId = 4

Code	Description
581	End user is out of prepay credit
592	Account not provisioned for global one- or two-way SMS
592	Account not provisioned for the requested channel
568	Destination address not provisioned for SMS
15201	MMS invalid destination address

Example error response

If a message fails because of a provider-side restriction, the response looks like this:


{
  "errorCode": 3004,
  "errorDescription": "Message rejected by the provider.",
  "dcaStatus": {
    "providerId": 1,
    "code": "488",
    "name": "SPAM_REJECT_UNVERIFIED_TFN",
    "description": "Spam Reject - Unverified TFN"
  }
}