Developer reference

SMS API Error Codes

What each SMSGatewayHub SMS API response code means and the exact fix, so your integration gets back to sending fast.

26 codes explainedFix for every codeDLT checksHTTP and JSON API

Create Free Account DLT Registration Help

000Code for an accepted request

26Response codes documented

3Digits in every SMS API code

24/7Support for integration issues

Quick answer

SMSGatewayHub's SMS API returns an ErrorCode in every JSON response. 000 means the request was accepted; codes 001 to 027 mean it was rejected before sending. The most common are 007 (invalid API key), 011 (IP restriction), 013 (invalid number), 015 (sender ID not on DLT), 021 (insufficient Pay As You Go balance) and 024 (DLT template mismatch). Operator-level DLT failures appear later in the delivery report.

Start here

How to read an API response

Every SMSGatewayHub SMS API call returns JSON with an ErrorCode and an ErrorMessage. 000 means the request was accepted; any other code means it was rejected before reaching the operator, so no message was sent for that request.

Field	Meaning
`ErrorCode`	Three-digit result code from the table below. Balance and delivery-report calls return `0` for success.
`ErrorMessage`	Plain-text description of the code.
`JobId`	ID of the submitted job. Use it with the DLR Status API.
`MessageData`	One entry per number with its `MessageId`.

An accepted request (000) can still fail at the operator, for example on a DLT scrubbing check. Those failures appear in the delivery report, not here. See DLT error codes and solutions.

All SMS API error codes at a glance

The full list of codes the SMS HTTP and JSON APIs can return. Codes 002 and 016 are not used.

Code	Message	Type	How to fix
`000`	Success	Request accepted	No action. Store the JobId and MessageId so you can match the delivery report later.
`001`	Login details cannot be blank	Authentication	Pass APIKey on every call. Check that your code is not dropping the parameter when the value is read from config or an environment variable.
`003`	Sender cannot be blank	Request	Add the senderid parameter with a 6-character DLT-approved header mapped to your account.
`004`	Message text cannot be blank	Request	Send a non-empty text parameter. URL-encode it so characters such as & and # do not cut the value short.
`005`	Message data cannot be blank	Request	For JSON or bulk calls, include the message array with at least one number and text pair.
`006`	Generic error	Request	Retry once after a short wait. If it repeats, send the full request (with the API key masked) and the response to support.
`007`	Username or password is invalid	Authentication	Copy the APIKey again from API Settings in the panel. Remove stray spaces and regenerate the key if it may have leaked.
`008`	Account not active	Account	The account is inactive or expired. Contact support or your account manager to activate it.
`009`	Account locked	Account	The account has been locked. Contact your account manager to find out why and to unlock it.
`010`	API restriction	Account	API access is not enabled for this account or route. Ask support to enable API sending.
`011`	IP address restriction	Security	IP whitelisting is on and the request came from another IP. Add your server's public IP in the panel or remove the restriction.
`012`	Invalid length of message text	Content	The text is longer than allowed. Shorten it, or check that a Unicode message is flagged correctly (70 characters per part instead of 160).
`013`	Mobile numbers not valid	Request	Use the country code plus the number (for India, 91 followed by 10 digits) with no +, spaces or leading zero. Separate multiple numbers with commas.
`014`	Account locked due to spam message	Compliance	Sending was stopped because of content flagged as spam. Contact support, review the content and send only DLT-approved templates.
`015`	Sender ID not valid	DLT	The header is not approved on DLT or not mapped to your account. Check the header and the PE-TM chain in your DLT portal and the panel.
`017`	Group ID not valid	Request	The group ID does not exist in your panel account. Fetch the correct ID from the contacts or groups section.
`018`	Multi message to group is not supported	Request	Send one text to a group, or use the bulk JSON call when every number needs a different message.
`019`	Schedule date is not valid	Scheduling	Use the documented date-time format and a future time. Check your server's time zone against IST.
`020`	Message or mobile number cannot be blank	Request	Every entry in the request needs both a number and a message.
`021`	Insufficient credits	Balance	Your Pay As You Go balance is too low for this send. Recharge, then retry. Call GetBalance before large campaigns.
`022`	Invalid JobId	Reports	The JobId does not belong to this account or is mistyped. Use the JobId exactly as returned by the Send SMS response.
`023`	Parameter missing	Request	A required parameter is absent. Compare your call with the parameter table in the developer docs (APIKey, senderid, channel, DCS, flashsms, number, text, route, EntityId, dlttemplateid).
`024`	Invalid template or template mismatch	DLT	The text does not match the approved DLT template. Check spaces, punctuation, line breaks, variable values and the dlttemplateid.
`025`	{Field} can not be blank or empty	Request	The field named in the message is empty. Fill it in, or remove it if it is optional.
`026`	Invalid date range	Reports	The from date must be before the to date, and both must use the documented format.
`027`	Invalid optin user	Compliance	The number has not opted in for this route. Collect and record consent before sending on an opt-in route.

Codes by type

Login, account and IP codes

These codes mean the platform could not identify you or your account is not allowed to send right now.

Code	Message	Type	How to fix
`001`	Login details cannot be blank	Authentication	Pass APIKey on every call. Check that your code is not dropping the parameter when the value is read from config or an environment variable.
`007`	Username or password is invalid	Authentication	Copy the APIKey again from API Settings in the panel. Remove stray spaces and regenerate the key if it may have leaked.
`008`	Account not active	Account	The account is inactive or expired. Contact support or your account manager to activate it.
`009`	Account locked	Account	The account has been locked. Contact your account manager to find out why and to unlock it.
`010`	API restriction	Account	API access is not enabled for this account or route. Ask support to enable API sending.
`011`	IP address restriction	Security	IP whitelisting is on and the request came from another IP. Add your server's public IP in the panel or remove the restriction.

Never put your API key in browser or app code. Call the API from your server and whitelist that server's IP.

Request and parameter codes

Most integration bugs show up here. Compare your call against the parameter table in the developer API docs.

Code	Message	Type	How to fix
`003`	Sender cannot be blank	Request	Add the senderid parameter with a 6-character DLT-approved header mapped to your account.
`004`	Message text cannot be blank	Request	Send a non-empty text parameter. URL-encode it so characters such as & and # do not cut the value short.
`005`	Message data cannot be blank	Request	For JSON or bulk calls, include the message array with at least one number and text pair.
`006`	Generic error	Request	Retry once after a short wait. If it repeats, send the full request (with the API key masked) and the response to support.
`012`	Invalid length of message text	Content	The text is longer than allowed. Shorten it, or check that a Unicode message is flagged correctly (70 characters per part instead of 160).
`013`	Mobile numbers not valid	Request	Use the country code plus the number (for India, 91 followed by 10 digits) with no +, spaces or leading zero. Separate multiple numbers with commas.
`017`	Group ID not valid	Request	The group ID does not exist in your panel account. Fetch the correct ID from the contacts or groups section.
`018`	Multi message to group is not supported	Request	Send one text to a group, or use the bulk JSON call when every number needs a different message.
`019`	Schedule date is not valid	Scheduling	Use the documented date-time format and a future time. Check your server's time zone against IST.
`020`	Message or mobile number cannot be blank	Request	Every entry in the request needs both a number and a message.
`022`	Invalid JobId	Reports	The JobId does not belong to this account or is mistyped. Use the JobId exactly as returned by the Send SMS response.
`023`	Parameter missing	Request	A required parameter is absent. Compare your call with the parameter table in the developer docs (APIKey, senderid, channel, DCS, flashsms, number, text, route, EntityId, dlttemplateid).
`025`	{Field} can not be blank or empty	Request	The field named in the message is empty. Fill it in, or remove it if it is optional.
`026`	Invalid date range	Reports	The from date must be before the to date, and both must use the documented format.

DLT, template and compliance codes

Under TRAI's TCCCPR rules every commercial SMS in India must use a registered header and a registered template. These codes mean the request failed that check on our side.

Code	Message	Type	How to fix
`014`	Account locked due to spam message	Compliance	Sending was stopped because of content flagged as spam. Contact support, review the content and send only DLT-approved templates.
`015`	Sender ID not valid	DLT	The header is not approved on DLT or not mapped to your account. Check the header and the PE-TM chain in your DLT portal and the panel.
`024`	Invalid template or template mismatch	DLT	The text does not match the approved DLT template. Check spaces, punctuation, line breaks, variable values and the dlttemplateid.
`027`	Invalid optin user	Compliance	The number has not opted in for this route. Collect and record consent before sending on an opt-in route.

Checklist for code 024

The fixed text matches the template character for character, including spaces and line breaks.
Each variable value fits the variable type registered in the template (numeric, alphanumeric, URL, callback number, email).
URLs, APKs and callback numbers in the text are whitelisted on DLT.
The dlttemplateid and EntityId belong to the same entity as the header.

Need help registering or fixing templates? See DLT registration and sample templates.

Balance code

SMSGatewayHub works on Pay As You Go, so a send is rejected when the balance cannot cover it.

Code	Message	Type	How to fix
`021`	Insufficient credits	Balance	Your Pay As You Go balance is too low for this send. Recharge, then retry. Call GetBalance before large campaigns.

Check the balance before large campaigns with the GetBalance API.

Other products

Error codes for email, DLT and other channels

DLT and operator codes

Delivery failures from operator scrubbing. See the DLT guide.

Email API codes

EC codes for the email API and SMTP relay. Email error codes.

RCS responses

Response format for RCS sends. RCS response.

WhatsApp responses

Template message responses. WhatsApp response.

Troubleshooting

Troubleshooting steps

Log the full request URL or body (mask the API key) and the full JSON response.
Find the code in the table above and apply the fix.
For 000 with no delivery, check the delivery report for the operator status.
Check platform status if many requests fail at once.
Still stuck? Contact support with the JobId and time of the request.

Retry only codes that can change on their own (006 and 021 after a recharge). Retrying 007, 015 or 024 without fixing the cause will fail again.

Frequently asked questions

What does error code 000 mean in the SMSGatewayHub API?

Code 000 means success: the request was accepted and a JobId was created. It does not confirm handset delivery. Check the delivery report with the JobId to see whether each message was delivered.

What is error 024 invalid template or template mismatch?

Error 024 means the message text does not match the DLT template registered for the dlttemplateid you sent. Check spaces, punctuation, line breaks and variable values, and make sure the template, header and entity ID belong to the same entity.

Why do I get error 007 username or password is invalid?

Error 007 means the APIKey is wrong. Copy it again from API Settings in the panel, remove spaces or line breaks, and regenerate it if it may have been exposed.

How do I fix error 011 IP address restriction?

IP whitelisting is enabled on your account and the request came from a different IP. Add your server's public IP in the panel or switch the restriction off.

What does error 015 sender ID not valid mean?

The header (sender ID) is not approved on DLT or not mapped to your SMSGatewayHub account. Check the header status in your DLT portal and ask support to map it if needed.

What should I do about error 021 insufficient credits?

Your Pay As You Go balance cannot cover the send. Recharge your account and retry. Calling the GetBalance API before large campaigns avoids this.

What is the difference between API error codes and DLT error codes?

API error codes are returned straight away when SMSGatewayHub rejects a request. DLT error codes come later in the delivery report when an operator rejects an accepted message during scrubbing.

Which error codes should I retry automatically?

Retry only errors that can clear on their own, such as 006 (generic error) or 021 after a recharge. Errors like 007, 013, 015 and 024 need a fix to the request first.

What does error 027 invalid optin user mean?

The number has not opted in for the route you used. Collect and record the customer's consent before sending on an opt-in route.

Need help staying compliant?

Our DLT team registers your entity, headers and templates and checks every campaign before it goes out.

Create Free Account ☎ 1800 102 1822

Simply Restart Your SMS Marketing Journey!