Gestione Errori

Documentazione completa dei codici errore restituiti dall'API UniMsg e come gestirli.

Formato Errore Standard

Tutti gli errori API seguono questo formato:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Descrizione leggibile dell'errore",
        "details": {
            "field": "to",
            "reason": "Formato non valido"
        }
    }
}

Errori per Categoria

Autenticazione (401)

Codice	Messaggio	Soluzione
UNAUTHORIZED	Token mancante	Includi header Authorization
INVALID_TOKEN	Token non valido	Verifica il formato del token
TOKEN_EXPIRED	Token scaduto	Richiedi un nuovo access token
INVALID_CLIENT	Credenziali errate	Verifica client_id e client_secret

Permessi (403)

Codice	Messaggio	Soluzione
INSUFFICIENT_SCOPE	Scope non autorizzato	Richiedi token con scope necessario
ACCOUNT_SUSPENDED	Account sospeso	Contatta il supporto
IP_NOT_ALLOWED	IP non in whitelist	Configura IP whitelist

Validazione (400/422)

Codice	Messaggio	Soluzione
INVALID_PHONE	Numero telefono non valido	Usa formato E.164 (+39...)
INVALID_EMAIL	Email non valida	Verifica formato email
INVALID_SENDER	Mittente non valido	Max 11 caratteri alfanumerici
MESSAGE_TOO_LONG	Messaggio troppo lungo	Max 1600 caratteri per SMS
MISSING_PARAMETER	Parametro obbligatorio mancante	Includi tutti i parametri required
INVALID_TEMPLATE	Template non trovato	Verifica nome template WhatsApp

Crediti (402)

Codice	Messaggio	Soluzione
INSUFFICIENT_CREDITS	Crediti insufficienti	Ricarica il tuo account

Risorse (404)

Codice	Messaggio	Soluzione
MESSAGE_NOT_FOUND	Messaggio non trovato	Verifica message_id
WEBHOOK_NOT_FOUND	Webhook non trovato	Verifica webhook_id
TEMPLATE_NOT_FOUND	Template non trovato	Verifica nome template

Rate Limiting (429)

Codice	Messaggio	Soluzione
RATE_LIMITED	Troppe richieste	Attendi e riprova, rispetta i limiti

Gateway (502/503)

Codice	Messaggio	Soluzione
GATEWAY_ERROR	Errore provider esterno	Riprova dopo qualche secondo
GATEWAY_UNAVAILABLE	Gateway non disponibile	Riprova più tardi

Server (500)

Codice	Messaggio	Soluzione
INTERNAL_ERROR	Errore interno	Contatta il supporto se persiste

Gestione Errori Best Practices

Esempio PHP

<?php
try {
    $response = $uniMsg->sms()->send([
        'to' => $phone,
        'message' => $text
    ]);

    if ($response['success']) {
        return $response['data']['message_id'];
    }
} catch (UniMsgException $e) {
    switch ($e->getCode()) {
        case 'INSUFFICIENT_CREDITS':
            // Notifica admin per ricarica
            notifyAdmin('Crediti esauriti');
            break;

        case 'INVALID_PHONE':
            // Errore utente, mostra messaggio
            showError('Numero di telefono non valido');
            break;

        case 'RATE_LIMITED':
            // Riprova dopo delay
            sleep(5);
            return $this->retry($phone, $text);

        case 'GATEWAY_ERROR':
        case 'INTERNAL_ERROR':
            // Log e notifica, riprova più tardi
            logError($e);
            throw new TemporaryFailureException();

        default:
            logError($e);
            throw $e;
    }
}

Retry Logic

Per errori temporanei (5xx, GATEWAY_ERROR, RATE_LIMITED), implementa retry con backoff esponenziale:

async function sendWithRetry(data, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            return await uniMsg.sms.send(data);
        } catch (error) {
            if (attempt === maxRetries) throw error;

            const isRetryable = [
                'GATEWAY_ERROR',
                'INTERNAL_ERROR',
                'RATE_LIMITED'
            ].includes(error.code);

            if (!isRetryable) throw error;

            const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
            await sleep(delay);
        }
    }
}