Guida pratica: Gestire gli errori

Introduzione

Questa guida illustra la gestione degli errori durante l’interazione con l’API C2C. La gestione corretta degli errori HTTP è essenziale per un’integrazione solida con qualsiasi servizio di terze parti.

Tipi di errori

Gli errori nell’integrazione possono avere varie origini, che si possono suddividere in quattro gruppi principali:

• Errori I/O: sono causati da operazioni hardware sul dispositivo, come operazioni di lettura/scrittura non riuscite
• Errori dell’applicazione: derivano da problemi nel codice dell’applicazione
• Errori di rete: si verificano nello stack di rete e vengono comunicati dalla libreria di rete
• Errori API: vengono generati dai servizi backend di Frame.io

Ogni categoria di errore richiede valutazioni specifiche per la gestione. Questa guida si concentra principalmente sugli errori API, anche se affronteremo le strategie generali per le altre categorie.

Come vengono restituiti gli errori API

L’API Frame.io comunica gli errori attraverso due meccanismi principali:

• Codici di stato: codici di errore HTTP che indicano la natura del problema
• Messaggi di errore: contenuto del payload che fornisce dettagli aggiuntivi sull’errore, specialmente quando più condizioni di errore condividono lo stesso codice di stato

Codici di stato degli errori

I codici di stato HTTP sono risposte numeriche standardizzate che comunicano l’esito di una richiesta HTTP. Per ulteriori informazioni, consulta la documentazione dei codici di stato HTTP di Mozilla o HTTP Cats per un approccio più visivo. Ogni endpoint dell’API Frame.io specifica un codice di stato di successo previsto, in genere 200 (OK), 201 (Created) o 204 (No Content). Puoi verificare la riuscita dell’operazione controllando questi codici specifici o confermando che il codice rientri nell’intervallo 200-299. I codici di stato superiori a 399 indicano degli errori. La maggior parte degli errori API restituisce codici 4XX (400-499), che indicano problemi lato client. Gli errori fuori da questo intervallo derivano solitamente dall’infrastruttura di rete tra il dispositivo e il nostro servizio, con un’eccezione particolare per il codice 500 (Internal Server Error), che indica un problema imprevisto all’interno del nostro server. Analogamente, una risposta 404 (Not Found) potrebbe essere generata da servizi intermedi invece che dal nostro backend, nonostante sia un codice 4XX.

Se riscontri codici di stato imprevisti, avvisa il nostro team.

Schemi dei payload di errore

Frame.io restituisce dettagli degli errori in due formati: semplice e dettagliato. La logica di gestione degli errori deve supportare entrambi i formati.

Schema di errore semplice

Ecco un esempio di richiesta non riuscita con un client_secret non corretto:

$
curl -X POST https://api.frame.io/v2/auth/device/code \
>
    --include \
>
    --header 'x-client-version: 2.0.0' \
>
    --form 'client_id=Some-Client-ID' \
>
    --form 'client_secret=bad_secret' \
>
    --form 'scope=asset_create offline'

Risposta:

HTTP/2 400
...
{"error":"invalid_client"}

Lo schema semplice contiene solo un singolo campo per l’identificazione dell’errore.

Schema di errore dettagliato

Per fare un confronto, ecco una richiesta senza autorizzazione adeguata:

$
curl -X POST https://api.frame.io/v2/devices/heartbeat \
>
    --header 'Authorization: Bearer bad-token' \
>
    --header 'x-client-version: 2.0.0' \
>
    | python -m json.tool

Risposta:

1
{
2
    "code": 409,
3
    "errors": [
4
        {
5
            "code": 409,
6
            "detail": "The channel you're uploading from is currently paused.",
7
            "status": 409,
8
            "title": "Channel Paused"
9
        }
10
    ],
11
    "message": "Channel Paused"
12
}

Gli errori dettagliati contengono un campo message che identifica il tipo di errore.

Come determinare il tipo di errore

Quando vanno gestiti gli errori di Frame.io, controlla prima la presenza di un payload di errore e poi passa al codice di stato HTTP se non è presente alcun payload.

Ecco un’implementazione di base per la gestione degli errori:

1
# Dict of known error codes: native errors.
2
ERROR_STATUS_MAP = {
3
    429: SlowDownError,
4
    ...
5
}
6
7
# Dict of known error messages: native errros.
8
ERROR_MESSAGE_MAP = {
9
   "Channel Paused": ChannelPausedError,
10
   "invalid_client": InvalidClientError,
11
   "slow_down": SlowDownError,
12
   ...
13
}
14
15
def _c2c_extract_error_message(response):
16
    """
17
    Gets the error message from an error payload. Returns `None` 
18
    if an error payload is not found.
19
    """
20
21
    # Try to decode the payload, if it is not JSON return `None`
22
    try:
23
        payload = response.json() 
24
    except JSONDecodeError:
25
       return None
26
27
    # Try the simple error schema first.
28
    message = payload.get("error", default=None)
29
    if message is not None:
30
        return message
31
32
    # Now try the detailed schema. Return None if we do not find one.
33
    return payload.get("message", default=None)
34
35
def _c2c_error_type_from_response(response):
36
    """
37
    Converts a bad HTTP response into an error.
38
    """
39
    error_message = _c2c_extract_error_message(response)
40
41
    # try to do a lookup of the error type by message.
42
    error_type = ERROR_MESSAGE_MAP.get(error_message, default=None) 
43
    if error_type is not None:
44
        return error_type()
45
46
    # If not, try to do a lookup by error code.
47
    error_type = ERROR_STATUS_MAP.get(response.status_code, default=None)
48
    if error_type is not None:
49
        return error_type()
50
51
    # Otherwise we are going to return an `UnknownAPIError` to signal that we
52
    # encoutnered an error from Frame.io's backend servers, but do not know the
53
    # message and/or status code.
54
    return UnknownAPIError(message=error_message)
55
56
def raise_on_frameio_error(response, expected_status):
57
    """
58
    Raises a native error from an HTTP response if the response indicates an error
59
    occured. Expected status should be the status we expect to get (200, 201, 204, 
60
    etc).
61
    """
62
63
    # If the status code is less than `400`, then it is not an error status code.
64
    if response.status < 400:
65
66
        # Check that the status code is the one we expected, otherwise raise an
67
        # error.
68
        if response.status != expected_status:
69
            raise UnexpectedStatusError(
70
                expected=expected_status, received=response.status
71
            )
72
73
        return None
74
75
    # Otherwise convert and raise a native error.
76
    raise _c2c_error_type_from_response(response)

Le tabelle di ricerca degli errori a cui si fa riferimento in questo esempio sono fornite alla fine di questa guida.

Errori AWS

Durante il caricamento dei chunk di file, interagisci direttamente con AWS S3, che ha il proprio formato di errore. Consulta la documentazione degli errori comuni di AWS per i dettagli. Come regola generale, gli errori AWS non irreversibili devono essere ritentati almeno una volta.

Gli errori AWS vengono restituiti come XML:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Error>
3
  <Code>NoSuchKey</Code>
4
  <Message>The resource you requested does not exist</Message>
5
  <Resource>/mybucket/myfoto.jpg</Resource> 
6
  <RequestId>4442587FB7D0A2F9</RequestId>
7
</Error>

L’elemento Code identifica il tipo di errore.

Nuovi tentativi per gli errori

Quando riprovare

Le tabelle degli errori in questa guida indicano quali errori API dovrebbero essere ritentati. Per errori non legati all’API r provenienti da operazioni I/O, librerie di rete o AWS, conviene riprovare quelli che potrebbero derivare da condizioni transitorie. La congestione di rete, le interruzioni temporanee del server o la perdita di pacchetti di solito giustificano nuovi tentativi. La maggior parte delle librerie di rete genera un errore di tipo TimeoutError quando una richiesta impiega troppo tempo, il che rappresenta un candidato ideale per un nuovo tentativo.

Nel dubbio, riprova una volta

Gli ambienti di calcolo possono avere problemi imprevedibili. Anche nel caso di errori che appaiono irreversibili, spesso vale la pena fare un nuovo tentativo. Stati temporanei del sistema, anomalie hardware (come alterazioni di bit causate da raggi cosmici) o condizioni rare della memoria possono causare errori apparentemente fatali che si risolvono al secondo tentativo. Tuttavia, non bisogna eseguire nuovi tentativi per alcuni errori. Ad esempio, una risposta 409: CHANNEL PAUSED durante la creazione di una risorsa indica che il dispositivo è in pausa e non dovrebbe eseguire caricamenti. Questo stato è deliberato ed è improbabile che cambi con un nuovo tentativo.

Backoff esponenziale

Frame.io implementa limiti di frequenza che, se vengono superati, producono un errore 429: Slow Down o uno stato 400 con questo payload:

HTTP/2 400
{"error":"slow_down"}

Quando ricevi queste risposte, implementa il backoff esponenziale per i nuovi tentativi. Una formula consigliata per calcolare il ritardo (in secondi) è:

1
delay = min(2 ** attempt / 2, 32.0)

Dove attempt inizia da 0. Questo produce ritardi di 0,5 s, 1 s, 2 s, 4 s, 8s, 16 s e 32 s. Tutti i tentativi successivi vengono effettuati dopo 32 secondi.

Il backoff esponenziale è essenziale per gli errori causati dai limiti di frequenza, ma è anche utile per gestire in generale i problemi di rete e I/O. Questo approccio consente la risoluzione di vincoli temporanei delle risorse senza un ulteriore carico dovuto ai nuovi tentativi.

Rilevamento dello stato di disconnessione

In caso di errori di rete, è possibile che Frame.io non sia raggiungibile per vari motivi:

• La rete locale non funziona
• I servizi di Frame.io stanno avendo dei problemi
• Un componente di rete intermedio non funziona

È importante rilevare queste condizioni. Quando un errore indica problemi di connettività, occorre implementare un’attività di monitoraggio che verifichi il ripristino del servizio e informi l’utente della disconnessione.

Attesa della connessione e dell’autorizzazione

Progetta l’applicazione in modo da evitare richieste non necessarie quando il dispositivo sta aggiornando l’autorizzazione, è in attesa dell’autorizzazione utente o non può raggiungere Frame.io. Ciò riduce il carico di rete e migliora l’esperienza utente.

Blocca tutte le chiamate API (tranne quelle a https://api.frame.io/health) quando rilevi uno stato di disconnessione. Quando si verificano problemi di connettività, avvia un’attività in background che effettua il polling dell’endpoint di stato e blocca ulteriori chiamate API finché la connettività non viene ripristinata.

Allo stesso modo, se il token scade, blocca le chiamate dipendenti dall’autorizzazione finché non viene rilasciato un nuovo token. Se l’aggiornamento del token non riesce, avvisa l’utente di eseguire nuovamente l’autenticazione.

Durante il polling per rilevare lo stato della connessione, applica lo stesso approccio di backoff esponenziale descritto in precedenza.

Timeout delle richieste

Configura valori di timeout appropriati per diversi tipi di richieste:

• Predefinito: 15 secondi per le richieste di base
• Aggiornamento dell’autorizzazione: 2 minuti per tenere conto di potenziali elaborazioni backend
• Caricamento dei chunk di file: 5 minuti per adattarsi a reti lente durante il trasferimento di dati più grandi

Esempio di gestore di nuovi tentativi

Ecco un’implementazione in pseudocodice che mostra la gestione degli errori con backoff esponenziale:

1
# List of errors we know are fatal and should not be retried.
2
FATAL_ERRORS = (
3
    ChannelPausedError,
4
    DevicesDisabledError,
5
    ...
6
)
7
8
# List of errors we know should be retried more than once.
9
RETRY_ERRORS = (
10
    TimeoutError,
11
    NotFoundError,
12
    SlowDownError,
13
    UnknownAPIError,
14
    ...
15
)
16
17
# List of errors that could be the result of Frame.io being unreachable.
18
DISCONNECTED_ERRORS = (
19
    TimeoutError,
20
    HttpClientError,
21
    ...
22
)
23
24
def retry_with_backoff(next_handler):
25
    """
26
    Middleware for retrying errors with exponential backoff.
27
    """
28
29
    def retry_handler(call, retry_count):
30
        """
31
        Handler for retrying c2c API calls with exponential backoff.
32
        """
33
34
        error = None
35
36
        # We will retry the call 8 times here, totalling 63.5 seconds +- ~32 seconds.
37
        for attempt in range(start=1, stop=retry_count + 1):
38
39
            # If we are attempting to reach an endpoint that requires authorization
40
            # we should wait unil we have valid authorization before attempting
41
            # a call. We need to do this each time in case our access_token
42
            # expires between attempts.
43
            C2C.wait_for_authorized(call)
44
45
            # Likewise, we should wait until we are connected to Frame.io to attempt
46
            # a call if we are not calling `https://api.frame.io/health`
47
            C2C.wait_for_connected(call)
48
49
            try:
50
                # Return the result on a success.
51
                return next_handler(call)
52
            except FATAL_ERRORS as error:
53
                # If we hit an error we know is fatal, raise the error without
54
                # retrying it.
55
                raise error
56
57
            except RETRY_ERRORS as error:
58
                # If we hit an error we know we should retry many times, continue,
59
                # but notify our client if we think we may have been disconnected.
60
                if type(error) in DISCONNECTED_ERRORS:
61
                    C2C.notify_disconnected()
62
63
            except BaseException as error:
64
                # Otherwise, do not retry the call more than once.
65
                if attempt > 1:
66
                    raise error
67
68
            # The delay for the next attempt should be no more than 32 seconds.
69
            # This algorithm will go: 0.5s, 1s, 2s, 4s, 8s, 16s, 32s, 32s, ...
70
            delay = min(2 ** attempt / 2, 32.0)
71
72
            # Add some randomness (jitter) to the delay (up to half the value of
73
            # the delay in either direction).
74
            delay += math.random(-delay, delay) / 2
75
76
            # Wait between retries
77
            sleep(delay)
78
79
        # If we have exhausted all retries,
80
        raise error
81
82
    return retry_handler

Tabelle degli errori

Le seguenti tabelle categorizzano gli errori dell’API Frame.io e forniscono indicazioni su come gestirli. Ecco cosa rappresenta ogni colonna:

Messaggio: l’identificatore del messaggio del payload dell’errore Codice HTTP: il codice di stato HTTP Tipo di errore: una categoria di errore concettuale (dettagliata nella sezione descriptions) Schema: il formato del payload dell’errore (semplice o dettagliato) Nuovo tentativo: consiglio per un nuovo tentativo (sì per tentativi multipli, una volta per un singolo tentativo, no per errori irreversibili) Gli asterischi (*) indicano valutazioni speciali dettagliate nella sezione Descrizioni.

Messaggi di errore di Frame.io

Codici di stato di Frame.io

Errori AWS

Consulta la documentazione di AWS per descrizioni dettagliate.

Descrizioni

AccessDenied

Restituito quando un utente rifiuta l’autorizzazione durante l’associazione dispositivo.

AuthorizationPending

Indica che l’utente non ha ancora inserito il codice di associazione dispositivo. Continua il polling dopo il periodo (interval) specificato nella risposta del codice dispositivo.

ChannelPaused

Il canale del dispositivo era in pausa quando è stata creata la risorsa. Non tentare di caricare nuovamente questa risorsa.

ExpiredToken

Il codice di associazione del dispositivo è scaduto. Genera un nuovo codice e riavvia il processo di associazione.

InternalServerError

Indica un problema imprevisto del backend. Riprova una volta e segnala gli errori 500 al nostro team al fine di indagarli. Tieni presente che alcuni problemi noti restituiscono errori 500 quando dovrebbero invece restituire InvalidRequest:

• Tentativo di caricamento su un canale del dispositivo inesistente
• Richiesta non valida di un numero di chunk personalizzato

InvalidArgument

Un parametro del payload conteneva un valore non valido. Verifica che i valori dei parametri corrispondano alle aspettative dell’API.

InvalidContentType

L’intestazione Content-Type della richiesta non è supportata. L’API accetta generalmente:

• form/multipart (solo endpoint di autorizzazione)
• application/x-www-form-urlencoded (tutti gli endpoint)
• application/json (endpoint non di autorizzazione)

InvalidClient

Le credenziali fornite (client_id, client_secret ecc.) non sono state riconosciute. Verifica le credenziali di integrazione.

InvalidClientVersion

L’intestazione x-client-version era duplicata o contiene una versione semantica non valida.

InvalidGrant

Il tipo di concessione delle autorizzazioni non è valido. Rivedi i valori corretti nelle guide di autorizzazione.

InvalidRequest

I parametri della richiesta o il formato del payload non sono corretti. Verifica i nomi dei campi e i formati dei valori.

Se l’errore compare durante l’aggiornamento del token, il token di aggiornamento è scaduto e occorre riavviare il processo di autorizzazione.

SlowDown

Hai superato i limiti di frequenza delle richieste. Implementa il backoff esponenziale per le richieste successive. Tieni presente che l’esecuzione di più richieste di codice del dispositivo sulla stessa connessione TCP può attivare questo errore. Crea nuove connessioni per ogni richiesta di abbinamento.

UnauthorizedClient

Indica in genere che l’access_token è scaduto o manca. Se ricevi questo errore, aggiorna il token prima di riprovare.

Se si verifica durante l’aggiornamento del token, devi riavviare il processo di autorizzazione e richiedere all’utente di riconnettersi.

Questo errore può anche verificarsi quando si accede a risorse al di fuori dell’ambito di autorizzazione del dispositivo o quando un progetto ha disabilitato i dispositivi C2C. Verifica di aver richiesto gli ambiti appropriati durante l’autorizzazione.

Se questo errore si verifica durante l’aggiornamento del token, l’intero processo di autorizzazione deve essere riavviato con l’intervento dell’utente.

Passaggi successivi

Ti incoraggiamo a contattare il nostro team per qualsiasi domanda, poi vai alla guida sui caricamenti avanzati. Saremo lieti di aiutarti nel tuo percorso di implementazione. Se non l’hai già fatto, consulta la guida Implementazione C2C: configurazione prima di procedere. Avrai bisogno dell’access_token ottenuto durante il processo di autenticazione e autorizzazione. Questa guida si basa su quella dedicata ai caricamenti di base e sulla guida sui caricamenti avanzati.