Errors

// Every error has the same shape: branch on "code", show "message" to humans (French)
{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "Solde de crédits insuffisant pour cet envoi. Aucun message envoyé.", "details": { "available": 3, "required": 4 } } }

// Maintenance: nothing was done (no SMS, no debit)
{ "error": { "code": "FEATURE_DISABLED", "message": "Maintenance de l'envoi de SMS jusqu'à 10 h.",
  "details": { "feature": "api.sms_send", "blocked_by": "api.sms_send", "message": "Maintenance de l'envoi de SMS jusqu'à 10 h.", "until": "2026-11-06T10:00:00+00:00" } } }

Over HTTP

curl -i -X POST "https://api.labyrinthe-rdc.com/api/public/v1/sms" \
  -H "Authorization: Bearer lsk_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"243812345678","body":"Bonjour"}'

# HTTP/1.1 503 Service Unavailable
# Retry-After: 1800            <- only when a return date is scheduled
# X-Request-Id: 5f0c2b9e-...   <- give it to support
# {"error":{"code":"FEATURE_DISABLED", ...}}

With the packages

<?php
use Labyrinthe\Connect\Client;
use Labyrinthe\Connect\Exception\ApiException;
use Labyrinthe\Connect\Exception\FeatureDisabledException;
use Labyrinthe\Connect\Exception\InsufficientCreditsException;
use Labyrinthe\Connect\Exception\RateLimitException;
use Labyrinthe\Connect\Exception\RecipientNotSendableException;

$client = new Client('lsk_test_xxxxxxxxxxxxxxxx'); // or Client::fromEnv() (LABYRINTHE_API_KEY)

try {
    $client->sms->send(to: '243812345678', body: 'Bonjour');
} catch (FeatureDisabledException $e) {
    // 503 maintenance: nothing was sent, no credit used
    $e->getFeature();      // 'api.sms_send'
    $e->getBlockedBy();    // 'api' when the whole API is off
    $e->getAdminMessage(); // platform message, or null
    $e->getUntil();        // ?DateTimeImmutable
    $e->getRetryAfter() !== null ? retryIn($e->getRetryAfter()) : queueForLater();
} catch (InsufficientCreditsException $e) {
    notifyTopUp($e->getAvailable(), $e->getRequired());
} catch (RecipientNotSendableException $e) {
    foreach ($e->getRejected() as $rejected) {
        echo $rejected->recipient, ' ', $rejected->reason->value, PHP_EOL;
    }
} catch (RateLimitException $e) {
    retryIn($e->getRetryAfter() ?? 60);
} catch (ApiException $e) {
    logger($e->getErrorCode(), $e->getStatusCode(), $e->getRequestId());
}