Errori

L’API di GetQR è in beta ed è disponibile per alcuni workspace selezionati. I dettagli possono cambiare prima del rilascio generale.

L’API di GetQR usa i codici di stato HTTP standard. Le richieste riuscite restituiscono 2xx. Quelle non riuscite restituiscono 4xx o 5xx con un corpo JSON che spiega cosa è andato storto.

Formato degli errori

Ogni errore ha la stessa struttura: un codice stabile, un messaggio leggibile e un link alla descrizione di quel codice.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}

string

obbligatorio

Codice di errore stabile e leggibile dalle macchine. Usalo nel tuo codice al posto del messaggio. Consulta Codici di errore.

string

obbligatorio

Descrizione leggibile del problema. Il testo può cambiare.

string

obbligatorio

Link alla descrizione del codice di errore nella documentazione API del tuo account GetQR.

Codici di errore

Codice	Stato HTTP	Quando si verifica
`bad_request`	400	La richiesta non è valida: il corpo non è JSON valido, all’header `Authorization` manca il prefisso `Bearer` , oppure l’azione non è consentita nello stato attuale della risorsa (ad esempio, annullare una creazione in blocco già terminata).
`unauthorized`	401	La chiave API manca o non è valida, ad esempio perché è stata rigenerata.
`forbidden`	403	L’abbonamento del proprietario del workspace non è attivo, oppure il tuo ruolo nel workspace non consente questa azione.
`exceeded_limit`	403	Hai raggiunto un limite del piano. Con il piano Single QR, succede quando crei o duplichi un QR code e il workspace ne ha già uno, o quando avvii una creazione in blocco.
`not_found`	404	La risorsa non esiste o non appartiene al tuo workspace, l’endpoint non esiste, oppure l’API non è abilitata per il tuo workspace.
`method_not_allowed`	405	L’endpoint esiste ma non accetta questo metodo HTTP. L’header `Allow` elenca i metodi accettati.
`conflict`	409	La richiesta è in conflitto con dati esistenti: lo slug del link breve è già occupato, una richiesta con la stessa `Idempotency-Key` è ancora in corso, una pianificazione si sovrappone a una esistente, oppure un archivio della creazione in blocco non è ancora pronto.
`invite_pending`	409	Sei stato invitato nel workspace ma non ti sei ancora unito. Le richieste con chiave API non lo restituiscono: il workspace della chiave è sempre uno di cui fai parte.
`invite_expired`	410	Il tuo invito al workspace è scaduto. Le richieste con chiave API non lo restituiscono, per lo stesso motivo.
`unprocessable_entity`	422	Il corpo o i parametri di query non hanno superato la validazione. Il messaggio indica il campo e cosa non va. Consulta Errori di validazione.
`rate_limit_exceeded`	429	La chiave API ha esaurito le richieste per la finestra attuale. Consulta Limiti di frequenza.
`internal_server_error`	500	Qualcosa è andato storto da parte nostra. Riprova più tardi e contatta l’assistenza se il problema persiste.

Errori di validazione

Quando il corpo o i parametri di query non superano la validazione, l’API risponde 422. Il messaggio descrive il primo campo non valido nel formato <issue>: <field>: <details>:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}

I campi annidati usano la notazione con il punto, ad esempio link.url.

Gestisci gli errori

Basa la logica su error.code, non su error.message.
Non ripetere senza modifiche le richieste con errori 4xx: correggi prima la richiesta. Fanno eccezione un 409 per una richiesta ancora in corso e il 429.
In caso di 429, attendi il numero di secondi indicato nell’header Retry-After. Consulta Limiti di frequenza.
Ripeti le richieste con errori 5xx con un backoff esponenziale.

Problemi comuni

Ogni richiesta restituisce 404 "This endpoint is not available."

L’API è in beta e non è ancora abilitata per il tuo workspace.

404 "This endpoint does not exist."

Il percorso è errato. Confrontalo con le pagine degli endpoint e verifica che inizi con /api/v1/.

403 "Access denied: This account does not have an active subscription."

L’abbonamento del proprietario del workspace è terminato. La chiave API torna a funzionare appena il proprietario si abbona di nuovo.

403 "API access is not available for this role."

Il tuo ruolo nel workspace è Viewer. Solo il proprietario del workspace e gli Editor possono usare l’API.

API

Formato degli errori

Codici di errore

Errori di validazione

Gestisci gli errori

Problemi comuni

Passaggi successivi

Limiti di frequenza

Autenticazione

​Formato degli errori

​Codici di errore

​Errori di validazione

​Gestisci gli errori

​Problemi comuni

​Passaggi successivi

Limiti di frequenza

Autenticazione

Formato degli errori

Codici di errore

Errori di validazione

Gestisci gli errori

Problemi comuni

Passaggi successivi