Fast2SMS API error 416: You don’t have sufficient wallet balance

Fast2SMS API error 416, “You don’t have sufficient wallet balance”, means your wallet does not have enough money for the messages in that request. Add money to the wallet and send again. One detail catches many developers: this error can come back with HTTP 200, so your code must check the return field, not only the HTTP status.

The exact errors

The SMS API (/dev/bulkV2 and /dev/custom) answers:

{"return":false,"status_code":416,"message":"You don't have sufficient wallet balance"}
  • If the balance is below the price of even one SMS, the reply comes with HTTP 200.
  • If the balance covers some messages but not the full request, the reply comes with HTTP 400.

Other APIs say the same thing in their own words:

API Message
Smart OTP send / resend Insufficient wallet balance. You need at least ₹{amount}
WhatsApp Insufficient wallet balance, you need at least ₹X…

Why it happens

Before a send, Fast2SMS checks that the wallet covers the cost. For DLT SMS the cost is your SMS rate × valid numbers × SMS parts. A message longer than 160 English characters, or 70 Hindi or other Unicode characters, uses more than one part. So a large list or a long message can need more balance than you expect.

When the request is refused for balance, nothing is sent and nothing is charged.

How to fix error 416

  1. Check your balance

    Your wallet balance is shown at the top of every panel page. From code, call the wallet API, which returns the balance and roughly how many SMS it covers.

  2. Add money to the wallet

    Click Add Amount at the top of the panel. Enter the amount, check the GST line and the total you pay, then click Continue and complete the payment. The minimum recharge is ₹100 at the time of writing.

    Top up Wallet screen with 1000 entered, the amount, GST at 18 percent and the total to pay, and a Continue button
    Top up Wallet: GST is added to the amount you enter.
  3. Send the request again

    Once the balance shows in the wallet, repeat the API call. Add sms_details=1 to an SMS request to see the SMS count and amount debited in the reply.

Code check

Always read return, because a low-balance reply may arrive with HTTP 200:

const r = await fetch("https://www.fast2sms.com/dev/bulkV2", {
  method: "POST",
  headers: { "authorization": process.env.F2S_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ route: "dlt", sender_id: "DMTRDS", message: "40001",
                         variables_values: "4821", numbers: "9999999999" })
});
const d = await r.json();
if (d.return === false) {
  if (d.status_code === 416) alertTeam("Fast2SMS wallet is low. Recharge now.");
  throw new Error(`Fast2SMS: ${d.status_code} ${d.message}`);
}

Check the balance before a big campaign:

curl -X POST "https://www.fast2sms.com/dev/wallet" -H "authorization: YOUR_API_KEY"
# {"return":true,"wallet":"5566.0100","sms_count":27830}

How to avoid it

  • Turn on Low Balance Notification in Account Setting, API Security. You get SMS and email alerts when the wallet is low.
  • Call the wallet API from your app every morning, or before each campaign, and alert your team below a level you choose.
  • Keep OTP traffic in mind. Every Smart OTP send and resend is charged, and a failed send with fallback uses a second message.
  • Treat 416 as “stop and recharge”, not as an error to retry.

Frequently asked questions

Why does the API return HTTP 200 but no SMS is sent?

Check the return field. A low-balance reply (416) can come with HTTP 200 and "return": false.

Am I charged when I get error 416?

No. The request is refused before sending, so nothing is debited.

How do I check my Fast2SMS balance by API?

Call POST https://www.fast2sms.com/dev/wallet with your key in the authorization header. The reply has wallet in rupees and sms_count.

What is the minimum recharge?

₹100 at the time of writing, plus GST.

My balance looks fine but I still get 416. Why?

The full request costs more than the balance. Count the numbers and SMS parts. Long or Unicode text uses more parts per number.