Limiti ed errori

Limiti di richieste

Entrambi contano per l'intero account: tutte le tue chiavi e gli assistenti IA collegati insieme.

• Il limite al minuto si ricarica in continuazione: torna una richiesta ogni secondo, fino a 60.
• Il limite giornaliero è una finestra di 24 ore, non un giorno di calendario. L'intestazione X-RateLimit-Reset-Day dice quando finisce.

Intestazioni dei limiti

Ogni risposta a una richiesta con una chiave valida porta:

Quando un limite è raggiunto, la risposta è 429 rate_limited con un'intestazione Retry-After: aspetta quel numero di secondi, poi invia di nuovo la richiesta.

Ogni risposta, errore o no, porta anche X-Request-Id.

La forma di un errore

Gli errori seguono il formato standard «problem details» (application/problem+json):

{
  "type": "https://gloriads.com/docs/api/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "limit must be between 1 and 100.",
  "issues": [
    {
      "path": "limit",
      "code": "invalid_value",
      "message": "limit must be between 1 and 100."
    }
  ],
  "request_id": "req_8fK2mQ7xLp3nR9sT1vWy"
}

• Testa code nel tuo script. Non cambia mai; detail è scritto per le persone e può essere riformulato.
• issues elenca ogni parametro non valido. Compare solo su invalid_request.
• Cita request_id quando contatti l'assistenza.

Codici di errore

invalid_request · 400 — Un parametro non è valido: un valore sconosciuto, un numero fuori intervallo, un cursore di pagina che non è nostro. issues dice quale parametro e perché.

api_key_in_query · 400 — La chiave è stata inviata nell'URL. Inviala nell'intestazione Authorization e revoca quella chiave: potrebbe essere già in un log.

unauthorized · 401 — Nessuna chiave, oppure una chiave sbagliata o revocata. La risposta non dice quale dei due casi, di proposito.

subscription_inactive · 403 — L'abbonamento dell'account è terminato. L'API funziona di nuovo appena l'abbonamento è attivo.

insufficient_scope · 403 — La chiave non può leggere. Ogni chiave creata oggi può leggere, quindi non dovresti mai vedere questo codice.

not_found · 404 — Non c'è nessun endpoint a questo percorso, oppure ciò che hai chiesto non esiste nel tuo account. Ciò che appartiene a un altro account riceve la stessa risposta.

method_not_allowed · 405 — L'API risponde solo a GET, perché è di sola lettura. L'intestazione Allow elenca ciò che accetta.

amazon_not_connected · 409 — /targets, /ads e /reports/streaming-tv leggono Amazon nel momento in cui chiedi, e Amazon Ads non è collegato o va ricollegato. Sistemalo in Impostazioni → Amazon Ads, in Gloriads.

rate_limited · 429 — Un limite è raggiunto. Aspetta il numero di secondi indicato in Retry-After.

internal_error · 500 — Qualcosa è andato storto da parte nostra. Riprova più tardi; se continua, mandaci il request_id.

amazon_unavailable · 502 — Amazon non ha risposto a /targets, /ads o /reports/streaming-tv, oppure non è riuscita a produrre il report TV in streaming. Riprova tra qualche minuto.

timeout · 504 — La risposta ha impiegato più di 30 secondi. Chiedi meno dati per volta.

Valori e pagine

• null significa «non esiste», mai zero.
• Gli elenchi lunghi arrivano in pagine. limit fissa la dimensione della pagina: da 1 a 100 (50 per impostazione predefinita); fino a 1000 (100 per impostazione predefinita) per campagne, gruppi di annunci, target e annunci; fino a 500 (100 per impostazione predefinita) per le righe di un'operazione. Quando has_more è true, rimanda next_cursor come cursor per ottenere la pagina successiva.
• Una pagina può essere più corta di limit quando un filtro tiene poche righe (i gruppi di annunci di una sola campagna). Continua a seguire next_cursor finché has_more non è false.