Límites y errores

Límites de peticiones

Los dos cuentan para toda la cuenta: todas las claves y los asistentes de IA conectados juntos.

• El límite por minuto se recarga de forma continua: cada segundo vuelve una petición, hasta 60.
• El límite por día es una ventana de 24 horas, no un día del calendario. La cabecera X-RateLimit-Reset-Day dice cuándo termina.

Cabeceras de límite

Cada respuesta a una petición con una clave válida lleva:

Cuando se alcanza un límite, la respuesta es 429 rate_limited con una cabecera Retry-After: espera ese número de segundos y vuelve a enviar la petición.

Cada respuesta, sea error o no, lleva también X-Request-Id.

La forma de un error

Los errores siguen el formato estándar «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"
}

• Comprueba code en tu script. Nunca cambia; detail está escrito para personas, en inglés, y puede reformularse.
• issues lista cada parámetro no válido. Solo aparece en invalid_request.
• Indica request_id cuando contactes con soporte.

Códigos de error

invalid_request · 400 — Un parámetro no es válido: un valor desconocido, una fecha que no existe, un periodo demasiado largo, un cursor de página que no es nuestro. issues dice qué parámetro y por qué.

api_key_in_query · 400 — La clave se envió en la URL. Envíala en la cabecera Authorization y revoca esa clave: puede que ya esté en un registro.

unauthorized · 401 — Sin clave, o con una clave incorrecta o revocada. La respuesta no dice cuál de los dos casos, a propósito.

subscription_inactive · 403 — La suscripción de la cuenta ha terminado. La API vuelve a funcionar en cuanto la suscripción está activa.

insufficient_scope · 403 — La clave no tiene permiso para leer. Todas las claves creadas hoy pueden leer, así que no deberías ver nunca este código.

not_found · 404 — No hay ningún endpoint en esta ruta, o lo que pides no existe en tu cuenta. Una serie de otra cuenta recibe la misma respuesta.

wrong_host · 404 — La petición fue a trueroyalties.com. Usa https://author.trueroyalties.com/api/v1.

method_not_allowed · 405 — La API solo responde a GET, porque es de solo lectura. La cabecera Allow lista lo que acepta.

rate_limited · 429 — Se ha alcanzado un límite. Espera los segundos que indica Retry-After.

internal_error · 500 — Algo ha fallado por nuestra parte. Vuelve a intentarlo más tarde; si sigue pasando, envíanos el request_id.

timeout · 504 — La respuesta tardó más de 30 segundos. Pide un periodo más corto.

Periodos

Los informes aceptan o un range relativo o dos fechas, nunca las dos cosas.

• 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. Sin ningún periodo, obtienes last_30_days, como en el panel.
• start_date y end_date (YYYY-MM-DD, los dos días incluidos) van juntos. Un periodo dura como máximo 366 días. Una fecha final posterior a hoy cuenta como hoy.
• all_time solo funciona en /reports/books.
• timezone (por ejemplo Europe/Madrid) decide qué día es «hoy» para un range. Sin ella, la API usa UTC.

Cada informe devuelve el period que usó realmente. /account, /books y /series no llevan periodo.

Monedas y redondeo

• currency puede ser USD, GBP, EUR, JPY, CAD, INR, PLN, SEK, BRL, MXN o AUD. Por defecto, tu moneda de informes (o USD si no es una de estas).
• Los importes son números redondeados a la unidad más pequeña de la moneda: céntimos, o yenes enteros. El beneficio neto se calcula antes de redondear, así que las líneas redondeadas de un informe pueden diferir en un céntimo de su total redondeado.
• Los ratios son decimales: un margin de 0.25 significa un 25 %.
• null significa «no existe», nunca cero. Un margen sin regalías es null, no 0.
• Las descargas gratuitas nunca cuentan como regalías. Tienen su propio endpoint, /free-units.

Filtros y páginas

• Los filtros aceptan valores separados por comas: marketplaces=US,UK,DE. Un valor desconocido se rechaza con 400 invalid_request, que lo nombra. GB se acepta para el Reino Unido.
• Las listas largas llegan por páginas. limit fija el tamaño de página, de 1 a 100 (50 por defecto). Cuando has_more es true, devuelve next_cursor en cursor para obtener la página siguiente.