Limites et erreurs

Limites de requêtes

Les deux comptent pour tout le compte : toutes tes clés et tes assistants IA connectés ensemble.

• La limite par minute se recharge en continu : une requête revient chaque seconde, jusqu'à 60.
• La limite par jour est une fenêtre de 24 heures, pas un jour calendaire. L'en-tête X-RateLimit-Reset-Day dit quand elle se termine.

En-têtes de limite

Chaque réponse à une requête avec une clé valide porte :

Quand une limite est atteinte, la réponse est 429 rate_limited avec un en-tête Retry-After : attends ce nombre de secondes, puis renvoie la requête.

Chaque réponse, erreur ou non, porte aussi X-Request-Id.

La forme d'une erreur

Les erreurs suivent le format 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"
}

• Teste code dans ton script. Il ne change jamais ; detail est écrit pour des humains, en anglais, et peut être reformulé.
• issues liste chaque paramètre invalide. Il n'apparaît que sur invalid_request.
• Cite request_id quand tu contactes le support.

Codes d'erreur

invalid_request · 400 — Un paramètre n'est pas valide : une valeur inconnue, une date qui n'existe pas, une période trop longue, un curseur de page qui n'est pas le nôtre. issues dit quel paramètre et pourquoi.

api_key_in_query · 400 — La clé a été envoyée dans l'URL. Envoie-la dans l'en-tête Authorization, et révoque cette clé : elle est peut-être déjà dans un journal.

unauthorized · 401 — Pas de clé, ou une clé fausse ou révoquée. La réponse ne dit pas laquelle, exprès.

subscription_inactive · 403 — L'abonnement du compte est terminé. L'API remarche dès que l'abonnement est de nouveau actif.

insufficient_scope · 403 — La clé n'a pas le droit de lire. Toutes les clés créées aujourd'hui peuvent lire : tu ne devrais jamais voir ce code.

not_found · 404 — Il n'y a pas d'endpoint à ce chemin, ou ce que tu demandes n'existe pas dans ton compte. Une série d'un autre compte reçoit la même réponse.

wrong_host · 404 — La requête est partie vers trueroyalties.com. Utilise https://author.trueroyalties.com/api/v1.

method_not_allowed · 405 — L'API ne répond qu'à GET, car elle est en lecture seule. L'en-tête Allow liste ce qu'elle accepte.

rate_limited · 429 — Une limite est atteinte. Attends le nombre de secondes indiqué dans Retry-After.

internal_error · 500 — Quelque chose a échoué de notre côté. Réessaie plus tard ; si ça continue, envoie-nous le request_id.

timeout · 504 — La réponse a pris plus de 30 secondes. Demande une période plus courte.

Périodes

Les rapports acceptent soit une plage relative range, soit deux dates — jamais les deux.

• 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. Sans aucune période, tu obtiens last_30_days, comme sur le tableau de bord.
• start_date et end_date (YYYY-MM-DD, les deux jours inclus) vont ensemble. Une période fait au plus 366 jours. Une date de fin après aujourd'hui compte comme aujourd'hui.
• all_time ne marche que sur /reports/books.
• timezone (par exemple Europe/Paris) décide quel jour est « aujourd'hui » pour une range. Sans lui, l'API utilise UTC.

Chaque rapport renvoie la period réellement utilisée. /account, /books et /series ne prennent pas de période.

Devises et arrondis

• currency peut valoir USD, GBP, EUR, JPY, CAD, INR, PLN, SEK, BRL, MXN ou AUD. Par défaut, ta devise de rapport (ou USD si elle n'en fait pas partie).
• Les montants sont des nombres arrondis à la plus petite unité de la devise : les centimes, ou le yen entier. Le bénéfice net est calculé avant l'arrondi : les lignes arrondies d'un rapport peuvent donc différer d'un centime de son total arrondi.
• Les ratios sont des décimaux : une margin de 0.25 veut dire 25 %.
• null veut dire « n'existe pas », jamais zéro. Une marge sans royalties vaut null, pas 0.
• Les téléchargements gratuits ne comptent jamais comme royalties. Ils ont leur propre endpoint, /free-units.

Filtres et pages

• Les filtres prennent des valeurs séparées par des virgules : marketplaces=US,UK,DE. Une valeur inconnue est refusée avec 400 invalid_request, qui la nomme. GB est accepté pour le Royaume-Uni.
• Les longues listes arrivent par pages. limit règle la taille d'une page, de 1 à 100 (50 par défaut). Quand has_more vaut true, renvoie next_cursor dans cursor pour obtenir la page suivante.