SMS API error codes and how to handle them

Every eSMS SMS API error comes back with an HTTP status and a JSON envelope whose error.code is a stable, machine-readable string such as country_not_enabled or insufficient_balance. Branch on that code, not on the message text: this guide lists the SMS API error codes you are likely to meet, what each means, how to fix it, and which are safe to retry. Refused sends are never charged.

Last reviewed: 29 October 2026

How to handle SMS API error codes

1. Read the error envelope

   Errors share one shape. error.code is what you branch on, error.message is for people, and error.details carries extra context such as required and available on a 402. The older detail field is kept for backward compatibility.

   HTTP/1.1 403 Forbidden
   X-Request-Id: 3f9a1c2b4d5e6f708192a3b4c5d6e7f8
   
   {
     "error": {
       "code": "country_not_enabled",
       "message": "Sending to Cameroon (CM) is not enabled for this account yet. ...",
       "request_id": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
       "details": { "to": "+237677123456", "country": "CM", "enable_url": "https://sms.esmsafrica.io/countries" }
     },
     "detail": { "code": "country_not_enabled", "...": "..." }
   }

2. Decide: retry or fix

   Treat 429 and 5xx as temporary and retry with backoff. Treat other 4xx codes as something to fix: retrying the same request gives the same answer. The official SDKs already retry the temporary cases for you.

3. Retry with the same Idempotency-Key

   Send an Idempotency-Key header and reuse it on every retry. If the first attempt actually went through, the retry returns the original result instead of sending and charging again. A plain HTTP example:

   async function sendWithPolicy(payload, idempotencyKey) {
     for (let attempt = 0; attempt < 4; attempt++) {
       const res = await fetch("https://sms.esmsafrica.io/api/messages/send", {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${process.env.ESMS_API_KEY}`,
           "Content-Type": "application/json",
           "Idempotency-Key": idempotencyKey,   // same key on every attempt
         },
         body: JSON.stringify(payload),
       });
       if (res.ok) return res.json();
   
       const body = await res.json().catch(() => ({}));
       const code = body.error?.code;
       const requestId = res.headers.get("X-Request-Id");
   
       if (res.status === 429 || res.status >= 500) {      // temporary: back off, retry
         await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
         continue;
       }
       // 4xx: retrying will not help, fix the cause
       throw Object.assign(new Error(body.error?.message), { status: res.status, code, requestId });
     }
     throw new Error("Gave up after retries");
   }

4. Log the request id

   Every response, success or error, carries X-Request-Id (also in error.request_id). Store it with the failure; it is the fastest way for support to find the exact call. You can also send your own X-Request-Id and it is echoed back.

SMS API error codes reference

The status shown is the HTTP status the API returns for that code today.

Common errors and how to fix them

Frequently asked questions

Am I charged when a send is refused?

No. Requests refused with an error are not charged, and a message that later fails at the network is refunded.

Which errors should I retry?

429 and 5xx, with backoff and the same Idempotency-Key. Fix 4xx errors instead of retrying them.

Why do I get 402 instead of 400 for low balance?

402 Payment Required is used for insufficient_balance so your code can catch it separately and prompt a top-up.

Where do failed calls show up?

Every API-key call is listed on the Request Logs page under DEVELOPERS, with its status and request id.

Related guides

• Developer guides: all articles
• Phone number formatting (E.164) for the SMS API
• SMS delivery statuses explained, including Confirming
• Switch on the countries you send to
• Get a sender ID: default vs custom
• Errors API reference

Ready? Create a free eSMS account, then create a test API key and send your first simulated message in minutes. Nothing is charged until you switch to a live key.