Limites e erros

Limites de requisições

Os dois valem para a conta inteira: todas as chaves e assistentes de IA conectados juntos.

• O limite por minuto se recarrega continuamente: a cada segundo volta uma requisição, até 60.
• O limite por dia é uma janela de 24 horas, não um dia do calendário. O cabeçalho X-RateLimit-Reset-Day diz quando ela termina.

Cabeçalhos de limite

Toda resposta a uma requisição com uma chave válida traz:

Quando um limite é atingido, a resposta é 429 rate_limited com um cabeçalho Retry-After: espere esse número de segundos e envie a requisição de novo.

Toda resposta, com erro ou não, também traz X-Request-Id.

O formato de um erro

Os erros seguem o formato padrão "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 no seu script. Ele nunca muda; detail é escrito para pessoas, em inglês, e pode ser reformulado.
• issues lista cada parâmetro inválido. Só aparece em invalid_request.
• Informe request_id quando falar com o suporte.

Códigos de erro

invalid_request · 400 — Um parâmetro não é válido: um valor desconhecido, uma data que não existe, um período longo demais, um cursor de página que não é nosso. issues diz qual parâmetro e por quê.

api_key_in_query · 400 — A chave foi enviada na URL. Envie-a no cabeçalho Authorization e revogue essa chave: ela pode já estar em um log.

unauthorized · 401 — Sem chave, ou com uma chave errada ou revogada. A resposta não diz qual dos dois casos, de propósito.

subscription_inactive · 403 — A assinatura da conta terminou. A API volta a funcionar assim que a assinatura estiver ativa.

insufficient_scope · 403 — A chave não tem permissão para ler. Todas as chaves criadas hoje podem ler, então você nunca deveria ver este código.

not_found · 404 — Não há endpoint neste caminho, ou o que você pediu não existe na sua conta. Uma série de outra conta recebe a mesma resposta.

wrong_host · 404 — A requisição foi para trueroyalties.com. Use https://author.trueroyalties.com/api/v1.

method_not_allowed · 405 — A API só responde a GET, porque é somente leitura. O cabeçalho Allow lista o que ela aceita.

rate_limited · 429 — Um limite foi atingido. Espere os segundos indicados em Retry-After.

internal_error · 500 — Algo falhou do nosso lado. Tente de novo mais tarde; se continuar, envie-nos o request_id.

timeout · 504 — A resposta levou mais de 30 segundos. Peça um período menor.

Períodos

Os relatórios aceitam ou um range relativo ou duas datas — nunca os dois.

• 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. Sem nenhum período, você recebe last_30_days, como no painel.
• start_date e end_date (YYYY-MM-DD, os dois dias incluídos) andam juntos. Um período tem no máximo 366 dias. Uma data final depois de hoje conta como hoje.
• all_time só funciona em /reports/books.
• timezone (por exemplo America/Sao_Paulo) decide qual dia é "hoje" para um range. Sem ele, a API usa UTC.

Todo relatório devolve o period realmente usado. /account, /books e /series não recebem período.

Moedas e arredondamento

• currency pode ser USD, GBP, EUR, JPY, CAD, INR, PLN, SEK, BRL, MXN ou AUD. Por padrão, sua moeda de relatório (ou USD se ela não for uma destas).
• Os valores são números arredondados para a menor unidade da moeda: centavos, ou ienes inteiros. O lucro líquido é calculado antes do arredondamento, então as linhas arredondadas de um relatório podem diferir em um centavo do total arredondado.
• As proporções são decimais: uma margin de 0.25 significa 25 %.
• null significa "não existe", nunca zero. Uma margem sem royalties é null, não 0.
• Downloads gratuitos nunca contam como royalties. Eles têm um endpoint próprio, /free-units.

Filtros e páginas

• Os filtros aceitam valores separados por vírgulas: marketplaces=US,UK,DE. Um valor desconhecido é recusado com 400 invalid_request, que o nomeia. GB é aceito para o Reino Unido.
• Listas longas chegam em páginas. limit define o tamanho da página, de 1 a 100 (50 por padrão). Quando has_more for true, envie next_cursor de volta em cursor para obter a próxima página.