Limiti ed errori

Limiti di richieste

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

• Il limite al minuto si ricarica di continuo: ogni secondo torna una richiesta, 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 quei 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://trueroyalties.com/docs/api/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "end_date must be on or after start_date.",
  "issues": [
    {
      "path": "end_date",
      "code": "invalid_value",
      "message": "end_date must be on or after start_date."
    }
  ],
  "request_id": "req_8fK2mQ7xLp3nR9sT1vWy"
}

• Controlla code nel tuo script. Non cambia mai; detail è scritto per le persone, in inglese, e può essere riformulato.
• issues elenca ogni parametro non valido. Compare solo con invalid_request.
• Indica request_id quando contatti il supporto.

Codici di errore

invalid_request · 400 — Un parametro non è valido: un valore sconosciuto, una data che non esiste, un periodo troppo lungo, 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, o 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 torna a funzionare appena l'abbonamento è di nuovo attivo.

insufficient_scope · 403 — La chiave non ha il permesso di leggere. Tutte le chiavi create oggi possono leggere, quindi non dovresti mai vedere questo codice.

not_found · 404 — Non c'è nessun endpoint a questo percorso, oppure ciò che chiedi non esiste nel tuo account. Una serie di un altro account riceve la stessa risposta.

wrong_host · 404 — La richiesta è andata a trueroyalties.com. Usa https://author.trueroyalties.com/api/v1.

method_not_allowed · 405 — L'API risponde solo a GET, perché è in sola lettura. L'intestazione Allow elenca cosa accetta.

rate_limited · 429 — Un limite è stato raggiunto. Aspetta i secondi indicati in Retry-After.

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

timeout · 504 — La risposta ha impiegato più di 30 secondi. Chiedi un periodo più breve.

Periodi

I report accettano o un range relativo o due date, mai entrambi.

• range: today, yesterday, last_7_days, last_14_days, last_30_days, last_60_days, last_90_days, this_month, last_month, this_year, last_year, all_time. Senza nessun periodo ottieni last_30_days, come nella dashboard.
• start_date e end_date (YYYY-MM-DD, entrambi i giorni inclusi) vanno insieme. Un periodo dura al massimo 366 giorni. Una data di fine dopo oggi vale come oggi.
• all_time funziona solo su /reports/books.
• timezone (per esempio Europe/Rome) decide quale giorno è «oggi» per un range. Senza, l'API usa UTC.

Ogni report restituisce il period davvero usato. /account, /books e /series non accettano un periodo.

Valute e arrotondamenti

• currency può essere USD, GBP, EUR, JPY, CAD, INR, PLN, SEK, BRL, MXN o AUD. Di default, la tua valuta di report (o USD se non è tra queste).
• Gli importi sono numeri arrotondati all'unità più piccola della valuta: centesimi, o yen interi. Il profitto netto è calcolato prima dell'arrotondamento, quindi le righe arrotondate di un report possono differire di un centesimo dal loro totale arrotondato.
• I rapporti sono decimali: un margin di 0.25 significa 25 %.
• null significa «non esiste», mai zero. Un margine senza royalty è null, non 0.
• I download gratuiti non contano mai come royalty. Hanno un endpoint proprio, /free-units.

Filtri e pagine

• I filtri accettano valori separati da virgole: marketplaces=US,UK,DE. Un valore sconosciuto viene rifiutato con 400 invalid_request, che lo nomina. GB è accettato per il Regno Unito.
• Gli elenchi lunghi arrivano a pagine. limit imposta la dimensione della pagina, da 1 a 100 (50 di default). Quando has_more è true, rimanda next_cursor in cursor per avere la pagina successiva.