Gestione degli errori e stati HTTP

HTTP/1.1 401 Unauthorized
X-XoPort-Deny-Reason: deny_token_required
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "api_version": "2.122.13",
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "deny_token_required",
    "message": "Authentication required. JSON/REST routes always require an OAuth2 token and check its scopes; the XML_PORT_IP_FILTER whitelist does not authorize them (changed in API 2.119.0). Obtain a token via POST /oauth/token (client_credentials grant)."
  }
}

Gli errori relativi ai parametri di richiesta contengono inoltre i campi details[], param e message per ogni errore (esempio nella pagina API di esportazione). Valutate error.code, non il testo del messaggio.

A partire dalla versione v2.119.0, in caso di richiesta rifiutata l'API indica il motivo nel campo reason; in caso di errore 401, lo indica anche nell'intestazione X-XoPort-Deny-Reason: ad esempio deny_token_required (401, richiesta senza token) o deny_ip_not_listed (403, indirizzo non presente in XOPORT_REST_IP_LIST; solo nel corpo del messaggio).

L'endpoint dei token POST /oauth/token risponde nel formato OAuth2 (error, error_description), non con questi codici: vedi "Errore all'endpoint dei token" più sotto.

Una modifica dell’ambito sul client ha effetto solo con il token successivo: un token già emesso mantiene gli ambiti al momento dell’emissione fino alla scadenza, ovvero fino a un’ora. È possibile revocare immediatamente l’accesso nel backend tramite «Revoca token» nel menu delle azioni del client (a partire dalla versione 4.9.168 di Shop); nelle versioni precedenti di Shop, disattivare e riattivare il client; il segreto rimane invariato. Una modifica al limite di richieste, invece, ha effetto immediato.

Nel log di utilizzo del client non compaiono le interruzioni dell’esportazione con codice HTTP 400 prima dell’esecuzione di una richiesta (errori di filtro, di scorrimento e di percorso) né la risposta 429. Chi cerca un errore in quel registro non troverà quindi questi casi; tuttavia, i codici 400 vengono comunque conteggiati ai fini del limite di richieste.

A partire dalla v2.122.11, Retry-After indica i secondi che devono trascorrere prima che venga accettata una nuova richiesta (da 1 a 3600), e il corpo della risposta riporta lo stesso numero come error.retry_after. A ciò si aggiungono le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, che ogni risposta invia a un client con limite di richieste (vedi client OAuth2).

HTTP/1.1 429 Too Many Requests
Retry-After: 1260
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792327500
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "api_version": "2.122.13",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit of 5000 requests per 3600 s (sliding window) exceeded.",
    "retry_after": 1260
  }
}

• Il valore determinante per il tentativo successivo è Retry-After. Nella maggior parte dei casi, «ora + Retry-After» corrisponde esattamente a X-RateLimit-Reset; se il limite di un client è stato appena ridotto, il valore risultante è Retry-After.
• Fino alla versione v2.122.10 (Shop fino alla 4.9.170) Retry-After era sempre 3600, non esisteva un campo retry_after e il messaggio era «Rate limit of 5000 requests/hour exceeded.». Prendete come riferimento error.code, mai il testo del messaggio.
• Una richiesta respinta (429) non viene conteggiata. È consigliabile distribuire un numero elevato di richieste in modo uniforme nell’arco dell’ora e rallentare non appena X-RateLimit-Remaining raggiunge lo 0, invece di attendere il 429.

POST /oauth/token risponde nel formato OAuth2 con error e error_description. A partire dalla v2.122.11, uno scope richiesto che non è leggibile (UTF-8 non valido o un elenco come scope[]=…) genera un errore HTTP 400 invalid_scope; non viene emesso alcun token. client_id o client_secret come elenco generano un errore HTTP 400 invalid_request. Per quanto riguarda il limite proprio dell’endpoint del token, Retry-After indica il tempo di attesa (da 1 a 300 secondi). Tutti gli errori relativi all’endpoint del token sono riportati nella sezione OAuth2 Clients.