Error Handling

Understand message failures through unified error codes and the raw dcaStatus block passed from the carrier.

To provide full transparency on message processing, our platform offers two layers of visibility:

Unified Error Codes (errorCode): standardized error categories managed by our platform.
DCA Status Block (dcaStatus): raw, detailed status information passed directly from the DCA.

The dcaStatus Object

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

Field	Description
`providerId`	Abstract provider identifier
`code`	Provider-specific status or error code
`name`	Provider-specific symbolic status/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, support investigations, and provider-specific diagnostics. Provider-specific codes and descriptions are passed through from the DCA and should not be treated as a stable public taxonomy.

Provider-Specific Error Examples

When the errorCode indicates a provider-level issue, you can use dcaStatus.providerId and dcaStatus.code to identify the provider-specific root cause.

The lists below contain examples of provider-specific error codes returned by DCAs.

dcaStatus.providerId = 1

Code	Description
15	Screening blocked the message
488	Spam Reject - Unverified TFN
1007	Destination address does not accept messages from Toll Free Numbers
1206	Destination number is currently unable to receive text messages (possibly no reception or handset is turned off). Check with the end user
1116	Destination number is not text enabled

dcaStatus.providerId = 4

Code	Description
581	End user 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 due to a provider-side restriction, the response will look 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"
  }
}