Limits und Fehler

Anfragelimits

Beide gelten für das ganze Konto: alle Schlüssel und verbundenen KI-Assistenten zusammen.

• Das Minutenlimit füllt sich laufend auf: Jede Sekunde kommt eine Anfrage zurück, bis 60.
• Das Tageslimit ist ein 24-Stunden-Fenster, kein Kalendertag. Der Header X-RateLimit-Reset-Day sagt, wann es endet.

Limit-Header

Jede Antwort auf eine Anfrage mit gültigem Schlüssel trägt:

Ist ein Limit erreicht, lautet die Antwort 429 rate_limited mit einem Header Retry-After: Warte so viele Sekunden und sende die Anfrage dann erneut.

Jede Antwort, ob Fehler oder nicht, trägt außerdem X-Request-Id.

Aufbau eines Fehlers

Fehler folgen dem Standardformat „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"
}

• Prüf in deinem Skript code. Er ändert sich nie; detail ist für Menschen geschrieben, auf Englisch, und kann umformuliert werden.
• issues listet jeden ungültigen Parameter. Es erscheint nur bei invalid_request.
• Nenn request_id, wenn du den Support kontaktierst.

Fehlercodes

invalid_request · 400 — Ein Parameter ist ungültig: ein unbekannter Wert, ein Datum, das es nicht gibt, ein zu langer Zeitraum, ein Seiten-Cursor, der nicht von uns stammt. issues sagt, welcher Parameter und warum.

api_key_in_query · 400 — Der Schlüssel wurde in der URL gesendet. Sende ihn im Header Authorization und widerrufe diesen Schlüssel: Er steht vielleicht schon in einem Log.

unauthorized · 401 — Kein Schlüssel, oder ein falscher oder widerrufener. Die Antwort sagt absichtlich nicht, welcher Fall vorliegt.

subscription_inactive · 403 — Das Abo des Kontos ist beendet. Die API funktioniert wieder, sobald das Abo aktiv ist.

insufficient_scope · 403 — Der Schlüssel darf nicht lesen. Jeder heute erstellte Schlüssel darf lesen, du solltest diesen Code also nie sehen.

not_found · 404 — Unter diesem Pfad gibt es keinen Endpoint, oder das Angefragte existiert in deinem Konto nicht. Eine Reihe eines anderen Kontos bekommt dieselbe Antwort.

wrong_host · 404 — Die Anfrage ging an trueroyalties.com. Verwende https://author.trueroyalties.com/api/v1.

method_not_allowed · 405 — Die API antwortet nur auf GET, weil sie nur lesend ist. Der Header Allow listet, was sie annimmt.

rate_limited · 429 — Ein Limit ist erreicht. Warte die Sekunden aus Retry-After.

internal_error · 500 — Bei uns ist etwas schiefgegangen. Versuch es später erneut; passiert es weiter, schick uns die request_id.

timeout · 504 — Die Antwort hat länger als 30 Sekunden gedauert. Frag einen kürzeren Zeitraum ab.

Zeiträume

Die Berichte nehmen entweder einen relativen range oder zwei Daten — nie beides.

• 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. Ohne Zeitraum bekommst du last_30_days, wie im Dashboard.
• start_date und end_date (YYYY-MM-DD, beide Tage eingeschlossen) gehören zusammen. Ein Zeitraum ist höchstens 366 Tage lang. Ein Enddatum nach heute zählt als heute.
• all_time funktioniert nur bei /reports/books.
• timezone (zum Beispiel Europe/Berlin) legt fest, welcher Tag für einen range „heute“ ist. Ohne sie nutzt die API UTC.

Jeder Bericht liefert die tatsächlich verwendete period zurück. /account, /books und /series nehmen keinen Zeitraum.

Währungen und Rundung

• currency kann USD, GBP, EUR, JPY, CAD, INR, PLN, SEK, BRL, MXN oder AUD sein. Standard ist deine Berichtswährung (oder USD, wenn sie nicht dazugehört).
• Beträge sind Zahlen, gerundet auf die kleinste Einheit der Währung: Cent oder ganze Yen. Der Nettogewinn wird vor dem Runden berechnet, daher können die gerundeten Zeilen eines Berichts um einen Cent von seiner gerundeten Summe abweichen.
• Verhältnisse sind Dezimalzahlen: Eine margin von 0.25 bedeutet 25 %.
• null bedeutet „existiert nicht“, nie null. Eine Marge ohne Tantiemen ist null, nicht 0.
• Gratis-Downloads zählen nie als Tantiemen. Sie haben einen eigenen Endpoint, /free-units.

Filter und Seiten

• Filter nehmen kommagetrennte Werte: marketplaces=US,UK,DE. Ein unbekannter Wert wird mit 400 invalid_request abgelehnt, das ihn nennt. GB wird für das Vereinigte Königreich akzeptiert.
• Lange Listen kommen seitenweise. limit legt die Seitengröße fest, von 1 bis 100 (standardmäßig 50). Ist has_more true, sende next_cursor als cursor zurück, um die nächste Seite zu bekommen.