Errori

SIP Caller utilizza i codici di stato HTTP standard per indicare se una richiesta è riuscita. I codici nell'intervallo 2xx indicano il successo, i codici nell'intervallo 4xx indicano un problema con la richiesta (ad esempio, un campo mancante o un record che non esiste), e i codici nell'intervallo 5xx indicano un problema da parte di SIP Caller.

Formato delle risposte di errore

Le risposte di errore hanno un corpo JSON che segue lo standard Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "One or more errors occurred.",
  "status": 404,
  "detail": "Campaign with id '01a0dedd-b9a2-729d-8e0a-4e3ad9197aea' not found",
  "instance": "/v1/accounts/ACCOUNT_ID/campaigns/01a0dedd-b9a2-729d-8e0a-4e3ad9197aea",
  "traceId": "0HN6QKQ1B2F3G:00000001"
}

Campo	Descrizione
type	Un URL che identifica il tipo di errore, in base al codice di stato HTTP.
title	Un riepilogo breve e generico dell'errore.
status	Il codice di stato HTTP.
detail	Una spiegazione leggibile di questo specifico errore. Non presente negli errori di convalida.
instance	Il percorso della richiesta che ha causato l'errore.
traceId	Un identificatore univoco della richiesta. Includilo quando contatti il supporto in merito a un errore.
errors	Solo negli errori 400 e 409: l'elenco dei messaggi per ogni campo non valido, come descritto di seguito.

I messaggi detail ed errors servono ad aiutare gli sviluppatori a comprendere il problema. Non analizzarli nel tuo codice, poiché il loro testo può cambiare: usa invece il codice di stato HTTP.

Errori di convalida

Quando uno o più campi della richiesta non sono validi, l'API restituisce un errore 400 Bad Request con un oggetto errors. Ogni chiave è il nome di un campo non valido (con i punti per i campi annidati), e ogni valore è l'elenco dei problemi riscontrati:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "/v1/accounts/ACCOUNT_ID/campaigns",
  "errors": {
    "name": ["Value must not be empty."],
    "maxAttempts": ["Value must be between 1 and 9."]
  },
  "traceId": "0HN6QKQ1B2F3G:00000002"
}

Tutti i campi non validi vengono segnalati contemporaneamente, così puoi correggerli in un unico passaggio. Gli errori nei parametri di query filter, sort e range vengono segnalati allo stesso modo, sotto quelle chiavi.

Codici di stato HTTP

Codice	Significato
200 OK	La richiesta è riuscita.
201 Created	La risorsa è stata creata. La risposta contiene la nuova risorsa.
400 Bad Request	La richiesta non è valida: manca un campo obbligatorio, un valore ha un formato errato o è fuori intervallo, oppure il JSON è malformato. Consulta il campo errors o detail.
401 Unauthorized	Non è stata fornita una API Key valida. Consulta Autenticazione.
403 Forbidden	La API Key non ha il permesso di eseguire l'operazione.
404 Not Found	La risorsa non esiste, oppure non appartiene all'account.
408 Request Timeout	Il corpo della richiesta è stato inviato troppo lentamente.
409 Conflict	La richiesta è in conflitto con lo stato attuale della risorsa. Ad esempio, un nome che deve essere univoco è già in uso, oppure una risorsa non può essere eliminata perché è in uso.
412 Precondition Failed	La risorsa è stata modificata da qualcun altro dall'ultima volta che l'hai letta. Consulta Aggiornamenti simultanei più avanti.
413 Payload Too Large	Il corpo della richiesta supera la dimensione massima di 20 MB.
429 Too Many Requests	Sono state inviate troppe richieste in poco tempo. Consulta Limiti di frequenza.
500 Internal Server Error	Si è verificato un problema da parte di SIP Caller. Il nostro team viene avvisato automaticamente. Puoi ritentare la richiesta più tardi.

Aggiornamenti simultanei

Per evitare che le modifiche vadano perse quando la stessa risorsa viene modificata contemporaneamente da utenti o applicazioni diversi, le richieste di modifica (ad esempio Modificare una campagna) richiedono un campo lastUpdatedAt. Deve contenere il valore updatedAt della risorsa, così come restituito l'ultima volta che l'hai ottenuta, creata o modificata.

Se nel frattempo la risorsa è stata modificata, il suo valore updatedAt non corrisponde più, e la modifica viene rifiutata con un errore 412 Precondition Failed:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.13",
  "title": "One or more errors occurred.",
  "status": 412,
  "detail": "Update aborted to prevent 'lost update' problem; retry with correct 'lastUpdatedAt' value",
  "instance": "/v1/accounts/ACCOUNT_ID/blackLists/BLACK_LIST_ID",
  "traceId": "0HN6QKQ1B2F3G:00000003"
}

Quando ricevi questo errore, ottieni di nuovo la risorsa, applica le tue modifiche all'ultima versione, e invia la modifica con il nuovo valore lastUpdatedAt.

Gestione degli errori

Ti consigliamo il seguente approccio nella tua integrazione:

• Errori 4xx (tranne 429): non ritentare la stessa richiesta, poiché fallirà di nuovo. Registra la risposta, incluso il traceId, e correggi la richiesta.
• Errori 429: attendi il numero di secondi indicato nell'intestazione Retry-After, e ritenta.
• Errori 5xx ed errori di rete: ritenta con un backoff esponenziale (ad esempio, dopo 1, 2, 4 e 8 secondi). Fai attenzione quando ritenti richieste che creano risorse o aggiungono numeri, poiché il primo tentativo potrebbe essere riuscito prima dell'errore: verifica lo stato attuale prima di ritentare.