Errori API e limiti di velocità

Gli errori restituiscono { "error": { "code": "…", "message": "…", "details": … } } con uno status HTTP corrispondente.

• 400 invalid_parameter: un parametro di query come since, until o outcome è malformato.
• 401 unauthorized: chiave mancante, non valida o revocata.
• 403 plan_required: l'accesso API richiede un piano Scale o superiore su almeno un sito web.
• 403 insufficient_scope: la chiave è di sola lettura.
• 429 cooldown, concurrency, daily_quota, monthly_quota, competitor_quota o host_busy: si applica un limite di audit SEO; vedi retry_at e Retry-After.
• 403 org_suspended: contatta il supporto.
• 404 not_found: la risorsa non esiste nella tua organizzazione.
• 409 conflict: il termine di ricerca esiste già per quel paese e dispositivo.
• 422 validation_failed / limit_exceeded / plan_required / project_unverified: vedi messaggio e dettagli.
• 429 rate_limited: attendi Retry-After secondi.
• 500 internal_error: riprova; contatta il supporto se persiste.
• 503 unavailable: l'API è temporaneamente non disponibile; riprova con backoff.

Limiti di velocità

120 richieste al minuto per chiave. Una risposta 429 include Retry-After: 60. Ogni richiesta è registrata contro la chiave, e l'ultimo utilizzo della chiave (aggiornato al massimo una volta al minuto) è mostrato in Impostazioni → Chiavi API.

Limiti del piano

Aggiungere o modificare termini non riduce mai silenziosamente i tuoi numeri: se una richiesta supererebbe il limite di termini di ricerca o clic al giorno del sito, fallisce con 422 e ti dice quanto resta.