Codici di errore

Questa pagina elenca tutti gli errori che le API possono restituire:

• i codici del campo error nelle risposte applicative, cioè negli endpoint sotto /api/;
• gli errori dell'endpoint del token (/oauth/token), che seguono il formato OAuth2;
• le poche risposte che non seguono nessuno dei due formati.

La struttura generale delle risposte è descritta in Convenzioni comuni delle risposte.

Come leggere un errore

• Il codice HTTP è il primo riferimento: dice di che tipo di errore si tratta e se ha senso ripetere la chiamata.
• Il campo error distingue i casi con lo stesso codice HTTP, ad esempio un 403 per scope mancante da un 403 per funzione non disponibile. Usalo nel tuo codice per decidere come gestire l'errore.
• Il campo message spiega il problema in inglese ed è pensato per chi sviluppa l'integrazione. Il testo può cambiare nel tempo: registralo nei log, ma non usarlo per riconoscere l'errore.
• L'header X-Request-Id identifica la richiesta: indicalo all'assistenza se hai bisogno di aiuto su una chiamata.

Riepilogo

Codice	Stato HTTP	Significato	Ripetere la chiamata?
1000	400	Dati non validi, con il dettaglio per campo in meta.errors	No: correggi i dati
1001	400	Richiesta non valida, senza dettaglio per campo	No: correggi la richiesta
1100	401	Token mancante, non valido, scaduto o revocato	Una sola volta, con un nuovo token
1101	403	Il token non ha gli scope richiesti	No: serve un token con altri scope
1102	403	Il token è per un'altra API	No
1200	404	Risorsa o endpoint inesistente	No
1202	405	Metodo HTTP non previsto per il path	No
1300	429	Troppe richieste	Sì, dopo i secondi di Retry-After
1400	409	Conflitto con una regola o con lo stato della risorsa	Solo dopo che lo stato è cambiato
1500	500	Errore interno	Sì, con attese crescenti (vedi sotto per le scritture)
1601	403	Operazione non consentita	No
1700	402	Pagamento rifiutato dal fornitore	No, non con lo stesso metodo di pagamento

Dettaglio dei codici

1000 · Dati non validi

Stato HTTP: 400 Bad Request

I dati inviati non rispettano lo schema dell'endpoint, ad esempio:

• manca un campo obbligatorio;
• un valore ha un tipo o un formato sbagliato, è fuori dai limiti o non è tra quelli ammessi;
• il corpo JSON contiene un campo che lo schema non prevede;
• nel corpo JSON un booleano non è true o false, ad esempio "1" o "yes";
• un parametro della query string non è valido, ad esempio per_page oltre il massimo consentito.

meta.errors contiene i messaggi di ciascun campo. La chiave è il percorso del campo: configuration.ram per un campo annidato, ids[3] per un elemento di una lista. Vedi Errori di validazione.

1001 · Richiesta non valida

Stato HTTP: 400 Bad Request

La richiesta non è valida, ma l'errore non riguarda un campo preciso, quindi meta è null. Succede ad esempio quando:

• il corpo della richiesta non è un JSON valido (Invalid JSON body: …);
• il corpo JSON non è un oggetto, ad esempio è una lista (JSON body must be a valid object);
• il servizio rifiuta un valore che dipende dai dati del tuo account o della risorsa.

Il motivo è nel campo message.

1100 · Token non utilizzabile

Stato HTTP: 401 Unauthorized

La richiesta non ha un token che si possa usare:

• manca l'header Authorization, oppure non usa lo schema Bearer;
• il token è malformato, ha una firma non valida o non è stato emesso da Shellrent;
• il token è scaduto o è stato revocato;
• il client OAuth che ha emesso il token è stato eliminato;
• l'account a cui appartiene il client è stato disattivato.

La risposta ha l'header WWW-Authenticate, ad esempio Bearer error="invalid_token", error_description="The access token has expired.". La descrizione distingue solo la scadenza e la revoca: gli altri motivi restano generici.

Cosa fare: richiedi un nuovo token e ripeti la chiamata una sola volta. Se l'errore si ripete, il problema non è la scadenza: controlla il client nel pannello. Non ripetere la chiamata all'infinito. Ogni risposta 401 conta nel limite per IP: oltre 30 al minuto, l'indirizzo riceve 1300 per il resto del minuto, anche con un token valido.

1101 · Scope mancanti

Stato HTTP: 403 Forbidden

Il token è valido, ma non include tutti gli scope che l'endpoint richiede. L'header WWW-Authenticate indica gli scope necessari, ad esempio Bearer error="insufficient_scope", error_description="…", scope="domains:read".

Cosa fare: assegna gli scope al client, se mancano, e richiedi un nuovo token che li includa. Vedi Scope e autorizzazioni.

1102 · Token per un'altra API

Stato HTTP: 403 Forbidden

Il token è valido, ma è stato emesso per un'altra API (audience diversa). Per le API pubbliche (/api/v3/…) serve un token con audience api-public.

1200 · Non trovato

Stato HTTP: 404 Not Found

• La risorsa non esiste.
• La risorsa appartiene a un altro account. Per motivi di sicurezza la risposta è identica a quella di una risorsa inesistente, compreso il messaggio, ad esempio Domain not found.
• Nessun endpoint corrisponde al path, ad esempio per un errore di battitura nell'URL. In questo caso il messaggio è Resource not found.

1202 · Metodo non previsto

Stato HTTP: 405 Method Not Allowed

Il path esiste, ma non con il metodo HTTP usato, ad esempio una DELETE su un endpoint di sola lettura. L'header Allow elenca i metodi ammessi.

1300 · Troppe richieste

Stato HTTP: 429 Too Many Requests

Hai superato uno dei limiti di utilizzo:

• il limite di richieste al minuto del client;
• il limite più stretto di un endpoint particolarmente oneroso;
• il tetto delle risposte 401 per IP (Too many requests without a valid access token.).

Cosa fare: attendi i secondi indicati dall'header Retry-After prima di riprovare.

L'endpoint del token ha un limite proprio, con un errore in formato OAuth2 (rate_limited, vedi sotto).

1400 · Conflitto

Stato HTTP: 409 Conflict

La richiesta è corretta, ma non si può eseguire per una regola o per lo stato attuale della risorsa, ad esempio:

• il servizio è sospeso, oppure l'hosting è in manutenzione;
• c'è già un'operazione in corso sulla stessa risorsa;
• è stato raggiunto un limite del servizio, ad esempio il numero massimo di elementi;
• la risorsa esiste già, oppure la funzione è già attiva;
• lo stato della risorsa non permette l'operazione, ad esempio un'azione che richiede il server acceso.

Cosa fare: leggi il motivo nel campo message. Ripetere la stessa chiamata dà lo stesso risultato finché lo stato non cambia, ad esempio finché non termina l'operazione in corso.

1500 · Errore interno

Stato HTTP: 500 Internal Server Error

Si è verificato un errore imprevisto (Internal server error). L'errore viene segnalato automaticamente al team tecnico.

Cosa fare: per le letture puoi riprovare con attese crescenti. Per le scritture, prima di riprovare verifica lo stato della risorsa: l'operazione potrebbe essere stata eseguita comunque. Se l'errore persiste, contatta l'assistenza indicando l'header X-Request-Id.

1601 · Operazione non consentita

Stato HTTP: 403 Forbidden

Il token è valido e ha gli scope richiesti, ma l'operazione non è consentita:

• la funzione non è inclusa nel servizio o nel piano, ad esempio gli snapshot automatici su un server che non li prevede o la posta su un hosting senza caselle;
• l'operazione è negata ai sub-account, cioè ai clienti di un rivenditore: ordini, pagamenti, fatture e note di credito, listino e alcune modifiche agli acquisti (This operation is not available to sub-accounts.). Gli endpoint interessati lo indicano nella documentazione tecnica;
• la richiesta arriva da un IP che non è tra quelli consentiti nelle impostazioni di sicurezza dell'account (The request comes from an IP address that is not allowed for this account.).

Cosa fare: non ripetere la chiamata: un nuovo token non cambia l'esito. Serve una modifica al servizio, all'account o all'IP di provenienza.

1700 · Pagamento rifiutato

Stato HTTP: 402 Payment Required

Il fornitore del pagamento ha rifiutato l'addebito, ad esempio per una carta scaduta o per fondi insufficienti. Il campo message riporta il motivo indicato dal fornitore.

Gli ordini restano da pagare: puoi pagarli di nuovo dopo aver risolto il problema, oppure con un altro metodo.

Errori dell'endpoint del token

L'endpoint POST /oauth/token non usa la struttura delle risposte applicative: segue il formato degli errori OAuth2 (RFC 6749, §5.2). La risposta contiene:

• error: il codice dell'errore;
• error_description: la descrizione dell'errore;
• hint, solo in alcuni errori: un suggerimento sul parametro da controllare;
• message: una copia di error_description, mantenuta per compatibilità. Usa error_description.

{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid, unknown, or malformed",
  "hint": "Check the `domains:write` scope",
  "message": "The requested scope is invalid, unknown, or malformed"
}

error	Stato HTTP	Quando
invalid_request	400	Manca client_id, oppure audience ha un valore non valido o non ammesso per il client
unsupported_grant_type	400	grant_type manca o non è client_credentials
invalid_scope	400	Uno degli scope richiesti non esiste o non è assegnato al client
unauthorized_client	400	Il client è autenticato, ma l'account a cui appartiene non ha l'autenticazione a due fattori attiva
invalid_client	401	Credenziali errate, client eliminato, oppure account disattivato o non ancora validato
access_denied	401	La richiesta arriva da un paese bloccato o da un IP segnalato per abusi
rate_limited	429	Più di 5 richieste in 15 secondi dallo stesso IP e client: attendi i secondi indicati da Retry-After
server_error	500	Errore imprevisto

Per risolvere unauthorized_client attiva l'autenticazione a due fattori sull'account: non serve creare un nuovo client.

Se invii le credenziali con l'autenticazione HTTP Basic, la risposta invalid_client ha anche l'header WWW-Authenticate: Basic realm="OAuth".

Nessuno di questi errori si risolve ripetendo la richiesta, tranne rate_limited (dopo l'attesa) e server_error. Per gli altri devi correggere la richiesta, il client o l'account.

Risposte fuori dal formato standard

Un path che non è né sotto /api/ né un endpoint OAuth, come la radice https://api.shellrent.com/, risponde 404 con un formato diverso:

{
  "data": null,
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

Di solito indica un URL di base sbagliato, ad esempio senza /api/v3. La stessa forma, con code uguale a server_error, si usa per un errore interno fuori da questi path.

API interne

Le API interne (/api/internal/v3/…) sono riservate agli amministratori e usano gli stessi codici delle API pubbliche, con queste differenze:

• 1601 se l'account del token non è un amministratore (The internal API is restricted to administrators.);
• 1102 se il token è stato emesso con l'audience api-public invece di api-internal;
• all'endpoint del token, invalid_scope se uno scope interno viene richiesto con l'audience api-public.

In sintesi

• Decidi come gestire un errore in base al codice HTTP e al campo error, non al testo di message.
• Un 401 si gestisce con un solo nuovo tentativo, dopo aver richiesto un nuovo token.
• Un 429 si gestisce attendendo i secondi di Retry-After.
• Un 500 su una scrittura richiede di verificare lo stato della risorsa prima di riprovare.
• 400, 402, 403, 404, 405 e 409 non si risolvono ripetendo la stessa chiamata.
• Gli errori di /oauth/token hanno il formato OAuth2, con error sempre testuale.