Errori

L'API Scavio utilizza codici di stato HTTP standard e restituisce risposte di errore strutturate per aiutarti a risolvere i problemi rapidamente.

Formato della risposta di errore

JSON

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable error description"
  }
}

Codici di stato

Stato	Codice	Descrizione
400	`bad_request`	Corpo della richiesta non valido o parametri richiesti mancanti
401	`unauthorized`	Chiave API mancante o non valida
403	`forbidden`	La chiave API non ha autorizzazione per questa azione
402	`insufficient_credits`	Crediti esauriti. Ricarica o aggiorna il tuo piano.
429	`rate_limit_exceeded`	Troppe richieste. Attendi e riprova.
500	`internal_error`	Errore del server. Riprova dopo un breve ritardo.

Errori comuni

Parametro di query mancante

400 Richiesta non valida

{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

search_type non valido

400 Richiesta non valida

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

Chiave API non valida

401 Non autorizzato

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Crediti esauriti

402 Pagamento richiesto

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

Limite di velocità superato

429 Troppe richieste

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Migliori pratiche

Controlla sempre il codice di stato HTTP prima di analizzare il corpo della risposta
Usa il campo error.code per la gestione programmatica degli errori
Usa il campo error.message per la registrazione e il debug
Implementa una logica di riprova con backoff esponenziale per errori 429 e 500
Non riprovare errori 400 o 401 -- correggi prima la richiesta

Codici di stato

Stato

Codice

Descrizione

400

bad_request

Corpo della richiesta non valido o parametri richiesti mancanti

401

unauthorized

Chiave API mancante o non valida

403

forbidden

La chiave API non ha autorizzazione per questa azione

402

insufficient_credits

Crediti esauriti. Ricarica o aggiorna il tuo piano.

429

rate_limit_exceeded

Troppe richieste. Attendi e riprova.

500

internal_error

Errore del server. Riprova dopo un breve ritardo.

Errori comuni

Parametro di query mancante

400 Richiesta non valida

{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

search_type non valido

400 Richiesta non valida

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

Chiave API non valida

401 Non autorizzato

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Crediti esauriti

402 Pagamento richiesto

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

Limite di velocità superato

429 Troppe richieste

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Migliori pratiche

Controlla sempre il codice di stato HTTP prima di analizzare il corpo della risposta

Usa il campo error.code per la gestione programmatica degli errori

Usa il campo error.message per la registrazione e il debug

Implementa una logica di riprova con backoff esponenziale per errori 429 e 500

Non riprovare errori 400 o 401 -- correggi prima la richiesta