Errori
La Partner API usa codici di stato HTTP standard e corpi di risposta JSON per spiegare perché una richiesta non è riuscita.
Struttura della risposta di errore
La maggior parte degli errori dell'API restituisce un corpo JSON con un messaggio e, dove disponibili, dettagli strutturati.
{
"success": false,
"message": "Request body.members[0].member_id is required"
}
Alcuni endpoint specifici di un dominio restituiscono uno stato e un motivo espliciti. Ad esempio, gli errori del controllo degli accessi includono campi come reason, door_id, facility_id ed event_id.
{
"status": "failed",
"reason": "device_offline",
"door_id": "00000000000000000000000000000007",
"facility_id": "550e8400-e29b-41d4-a716-446655440000",
"event_id": "00000000-0000-0000-0000-000000000045"
}
Codici di stato
400 Bad Request
La richiesta non è formata correttamente o mancano campi obbligatori. Correggi la richiesta prima di riprovare.
401 Unauthorized
L'autenticazione non è riuscita. Verifica di usare HTTP Basic Auth con la tua chiave segreta API come nome utente e una password vuota.
403 Forbidden
La chiave è valida, ma l'operazione non è consentita. Le cause comuni includono l'uso di una chiave di sola lettura per un'operazione di scrittura o il tentativo di accedere a una struttura in cui la tua integrazione non è attivata.
404 Not Found
La risorsa richiesta non è stata trovata o non è disponibile per la tua integrazione.
409 Conflict
La richiesta è in conflitto con lo stato attuale della risorsa. Nel controllo degli accessi, ad esempio, un Door/Gate Controller può trovarsi in modalità di manutenzione.
422 Unprocessable Entity
La richiesta è un JSON valido, ma non supera la convalida semantica. Correggi i dati prima di riprovare.
429 Too Many Requests
L'integrazione ha superato il limite di frequenza documentato. Riprova con un backoff esponenziale.
500 Internal Server Error
Il Performance Hub non è riuscito a completare la richiesta a causa di un errore interno. Riprova con un backoff. Se il problema persiste, contatta l'assistenza indicando l'endpoint, il timestamp e il corpo della risposta.
503 Service Unavailable
Un servizio o un dispositivo da cui dipende la richiesta non è disponibile. Per gli sblocchi dei Door/Gate Controller, può significare che il controller è offline.
504 Gateway Timeout
L'operazione è scaduta. Per gli sblocchi dei Door/Gate Controller, significa che lo sblocco non è stato confermato entro il tempo limite.
Errori delle Access Time Windows
La convalida delle finestre non riesce prima che l'istantanea non valida venga scritta. Le cause comuni per cui non ha senso riprovare includono:
access_time_windows_revisionmancante quandoaccess_time_windowsè presente.- Valori epoch di tipo stringa, a virgola mobile o probabilmente espressi in millisecondi.
- Un fuso orario IANA non valido, un intervallo invertito, un
external_idduplicato, blocchi settimanali sovrapposti o un blocco notturno non suddiviso. - Un valore al di fuori dei limiti documentati di numero, lunghezza o durata.
Una revisione ripetuta con un contenuto normalizzato diverso genera un 409 Conflict. Esegui la riconciliazione con lo stato autorevole più recente e assegna una revisione più nuova; non continuare a riprovare la coppia in conflitto. Una revisione più vecchia viene segnalata come istantanea obsoleta saltata, invece di poter sovrascrivere uno stato più recente. Uno scope_key sconosciuto o non mappato nega l'autorizzazione per impostazione predefinita e va trattato come un avviso di configurazione.
Se la consegna va in timeout o riceve un 5xx temporaneo, riprova con la stessa identica istantanea normalizzata e la stessa revisione. Se il recupero dalla fonte a monte non è riuscito, ometti completamente il campo delle finestre; non sostituirlo mai con un array vuoto.
Indicazioni sui nuovi tentativi
Riprova questi errori con un backoff esponenziale e un numero limitato di tentativi:
429500502503504
Non riprovare questi errori alla cieca:
400401403404409422
Per il controllo degli accessi, considera sempre le risposte di timeout e offline come sblocchi non riusciti, a meno che le tue regole di accesso e i tuoi processi di sicurezza non stabiliscano diversamente.
Dettagli da includere per l'assistenza
Quando contatti l'assistenza, includi:
- Endpoint e metodo HTTP.
- Data, ora e fuso orario.
- ID della chiave partner, non la chiave segreta.
- Identificatore della struttura usato.
- ID del record di origine nel tuo sistema.
- Stato e corpo della risposta.
event_idocommand_id, se disponibili.