Limieten en fouten

Verzoeklimieten

Beide gelden voor het hele account: alle sleutels en gekoppelde AI-assistenten samen.

• De minuutlimiet vult zich doorlopend aan: elke seconde komt er één verzoek bij, tot 60.
• De daglimiet is een venster van 24 uur, geen kalenderdag. De header X-RateLimit-Reset-Day zegt wanneer het afloopt.

Limietheaders

Elk antwoord op een verzoek met een geldige sleutel bevat:

Als een limiet is bereikt, is het antwoord 429 rate_limited met een header Retry-After: wacht dat aantal seconden en stuur het verzoek dan opnieuw.

Elk antwoord, fout of niet, bevat ook X-Request-Id.

De vorm van een fout

Fouten volgen het standaardformaat "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"
}

• Controleer code in je script. Die verandert nooit; detail is geschreven voor mensen, in het Engels, en kan anders geformuleerd worden.
• issues noemt elke ongeldige parameter. Het staat alleen bij invalid_request.
• Noem request_id als je contact opneemt met support.

Foutcodes

invalid_request · 400 — Een parameter is ongeldig: een onbekende waarde, een datum die niet bestaat, een te lange periode, een paginacursor die niet van ons is. issues zegt welke parameter en waarom.

api_key_in_query · 400 — De sleutel is in de URL verstuurd. Stuur hem in de header Authorization en trek die sleutel in: hij staat misschien al in een log.

unauthorized · 401 — Geen sleutel, of een verkeerde of ingetrokken sleutel. Het antwoord zegt bewust niet welke van de twee.

subscription_inactive · 403 — Het abonnement van het account is afgelopen. De API werkt weer zodra het abonnement actief is.

insufficient_scope · 403 — De sleutel mag niet lezen. Elke sleutel die vandaag wordt aangemaakt mag lezen, dus deze code zou je nooit moeten zien.

not_found · 404 — Er is geen endpoint op dit pad, of wat je vraagt bestaat niet in je account. Een reeks van een ander account krijgt hetzelfde antwoord.

wrong_host · 404 — Het verzoek ging naar trueroyalties.com. Gebruik https://author.trueroyalties.com/api/v1.

method_not_allowed · 405 — De API antwoordt alleen op GET, omdat hij alleen-lezen is. De header Allow noemt wat hij accepteert.

rate_limited · 429 — Een limiet is bereikt. Wacht het aantal seconden uit Retry-After.

internal_error · 500 — Er ging bij ons iets mis. Probeer het later opnieuw; blijft het gebeuren, stuur ons dan de request_id.

timeout · 504 — Het antwoord duurde langer dan 30 seconden. Vraag een kortere periode op.

Periodes

De rapporten nemen óf een relatieve range óf twee datums — nooit allebei.

• 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. Zonder periode krijg je last_30_days, zoals op het dashboard.
• start_date en end_date (YYYY-MM-DD, beide dagen inbegrepen) horen bij elkaar. Een periode is maximaal 366 dagen lang. Een einddatum na vandaag telt als vandaag.
• all_time werkt alleen bij /reports/books.
• timezone (bijvoorbeeld Europe/Amsterdam) bepaalt welke dag "vandaag" is voor een range. Zonder gebruikt de API UTC.

Elk rapport geeft de period terug die echt is gebruikt. /account, /books en /series nemen geen periode.

Valuta en afronding

• currency kan USD, GBP, EUR, JPY, CAD, INR, PLN, SEK, BRL, MXN of AUD zijn. Standaard je rapportagevaluta (of USD als die er niet bij zit).
• Bedragen zijn getallen, afgerond op de kleinste eenheid van de valuta: centen, of hele yen. De nettowinst wordt vóór het afronden berekend, dus de afgeronde regels van een rapport kunnen een cent afwijken van het afgeronde totaal.
• Verhoudingen zijn decimalen: een margin van 0.25 betekent 25 %.
• null betekent "bestaat niet", nooit nul. Een marge zonder royalty's is null, niet 0.
• Gratis downloads tellen nooit als royalty's. Ze hebben een eigen endpoint, /free-units.

Filters en pagina's

• Filters nemen waarden gescheiden door komma's: marketplaces=US,UK,DE. Een onbekende waarde wordt geweigerd met 400 invalid_request, dat hem noemt. GB wordt geaccepteerd voor het Verenigd Koninkrijk.
• Lange lijsten komen per pagina. limit bepaalt de paginagrootte, van 1 tot 100 (standaard 50). Als has_more true is, stuur je next_cursor terug als cursor om de volgende pagina te krijgen.