Manage withdrawals and SMS line in case of failure to send (architecture and code)

Restarting a backlog SMS after a failure without analyzing the cause can result in massive overload (sending the same message to the customer 15 times), blocking your account by the [spam mechanism of the gateway] (/fr/blog/throttling-sms-au-maroc-a-qual-speed-can-you-really/), or flooding an already saturated network.

Here’s how to architect smart SMS failure management in a production environment, with resilient queues.

Imagine that Maroc Telecom (IAM) is undergoing a micro-cutting network of 2 minutes. Your system is trying to send 1000 urgent transaction alerts. The API returns a timeout or a server error HTTP 503. If your code makes a simple while(failed) {retry(); }, you will bombard the API with 1000 additional requests every second. As soon as the network is restored, the waiting row of the gateway will receive 50 000 requests at a time, which will likely cause it to collapse again.

Before considering a Retry, your code must read the HTTP error code or the DLR status of the API.

Never repeat (Permanent Error): - HTTP 400: The destination number is incorrectly formatted. - HTTP 401 / 403: Your API key has expired or the Sender ID is blocked. - DLR Failed: The operator confirms that the number does not exist.

When to reset (Temporary Error): - HTTP 429: You hit the speed limit (Rate Limit). - HTTP 500 / 502 / 503: The SMS gateway or Moroccan network connection is temporarily unavailable.

The Exponential Backoff is an algorithm that spaces the time between each reset attempt. Instead of trying every second, you try again after 2 seconds, then 4, then 8, then 16. A "Jitter" (a random variation) is added to it to prevent all your server processes from performing the reset at exactly the same microsecond (causing a new peak).

In modern architectures, retry is not managed in the HTTP controller. The message is pushed into a Message Broker (such as Redis) and a Worker is left to handle it.

In PHP (Laravel Queues) Laravel elegantly manages the exponential backoff directly in the properties of your "Jobs".

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendSmsNotification implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $phoneNumber;
    public $message;

    // Nombre maximal de tentatives (ex: abandonner après 5 essais)
    public $tries = 5;

    // Algorithme de recul : réessayer après 2s, 10s, 30s, 60s
    public function backoff()
    {
        return [2, 10, 30, 60];
    }

    public function handle()
    {
        $response = EnvoiSmsApi::send($this->phoneNumber, $this->message);

        // Si l'API renvoie un 400 (erreur permanente), on abandonne tout de suite
        if ($response->status === 400) {
            $this->fail(new \Exception('Numéro invalide, abandon.'));
            return;
        }

        // Si c'est une erreur 503, la fonction va naturellement throw une exception
        // et Laravel replacera le Job dans la file d'attente avec le backoff prévu.
        if (!$response->successful()) {
            throw new \Exception('Erreur temporaire API.');
        }
    }
}

The OTP expiration rule If you manage sending codes OTP for 2FA authentication, a retry can be dangerous. If the SMS ends up arriving 15 minutes later after 4 network retreats, the code generated in your database will already expire, generating customer frustration. For critical OTPs, limit the tries to a maximum of 2, and if this fails, instead implement a business Fallback (propose a voice call or [send WhatsApp]/fr/blog/whatsapp-pot-vs-sm-s-maroc/)) directly on the user interface, rather than re-send the SMS silently.