Errors & status codes

There are two distinct things developers call a "status" in a CPaaS platform, and mixing them up is the most common source of integration bugs:

API response status: did TextCall accept your request? Returned synchronously as an HTTP status code.
Delivery status: what happened to the message or verification afterwards? Delivered asynchronously via webhook, or on request via GET.

Below is a full list of TextCall API error codes. Each error returns a numeric error_code and a human-readable error_message.

Error format

{
  "request_id": "01J8Z3K9QW4T7VXR2MB6C0YHN5",
  "status": "FAILED",
  "error_code": 1001,
  "error_message": "recipients is required"
}

Two exceptions to be aware of:

Verify create, list, get, and cancel omit status and return error_code and error_message alongside request_id. An error_code can be present on a 200.
Verify confirm returns success and message instead of error_code.

HTTP status codes

Code	Description
200	OK. Check the body — an error_code may still be present on Verify create.
400	Bad request. A validation or business rule failed.
404	Not found. The resource does not exist under this account.
500	Internal server error. Retry with backoff.

1000–1999

Code	Message	Description
1000	{{entity}}already exists	The named resource already exists.
1001	{{field}} is required	A required field is missing.
1002	{{phone_number}} is not valid.	The number is not in E.164 format.
1003	{{phone_number}} is not valid.	Correctly formatted but not a valid or routable number.
1004	{{code}} is not valid	The submitted OTP does not match. The attempt counter is incremented.
1005	Default application cannot be archived.	Your account's default application cannot be archived.
1006	{{brand}} brand id does not match settings brand id.	The template's brand ID does not match the brand ID in your application settings.
1007	{{custom_otp}} OTP length does not match settings OTP length.	The supplied custom_otp is not the OTP length configured for the application.
1008	{{channel}} channel is not configured for this application.	The channel is not configured for this application.
1009	Expiration is less than the sum of channel fallback times.	The channel fallback times add up to more than the verification expiry.
1010	{{channel}} channel is not supported.	The channel is not supported. Messaging supports SMS only.
1011	{{resource}} not found.	No such resource under this account. Usually returned with HTTP 404.
1012	{{channel}} channel is disabled.	The channel is configured but currently disabled.
1013	Message delivery failed. {{failure_reason}}	Delivery failed downstream. Transient on some destinations.
1014	Insufficient funds.	Insufficient balance or credit to complete the service.
1015	Max number of tries reached.	Too many incorrect codes attempts
1016	Verification cancelled.	The verification was cancelled and can no longer be confirmed.
1017	{{brand}} is not approved.	The named sender ID, template, or brand is not approved for use.
1018	Brand identifier is not numeric.	The brand identifier must contain digits only.
1019	Message expired before send.	The message reached the end of its validity_period while still queued, or the message reached the end of its ttl while not delivered

5000–5999

Code	Message	Description
5000	Unknown error	An unexpected server-side error. Retry with backoff.