Limites e erros

Limites de requisições

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

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

Cabeçalhos de limite de taxa

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://gloriads.com/docs/api/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "limit must be between 1 and 100.",
  "issues": [
    {
      "path": "limit",
      "code": "invalid_value",
      "message": "limit must be between 1 and 100."
    }
  ],
  "request_id": "req_8fK2mQ7xLp3nR9sT1vWy"
}

• Teste code no seu script. Ele nunca muda; detail é escrito para pessoas e pode ser reformulado.
• issues lista cada parâmetro inválido. Ele só aparece em invalid_request.
• Informe o request_id quando entrar em contato com o suporte.

Códigos de erro

invalid_request · 400 — Um parâmetro não é válido: um valor desconhecido, um número fora do intervalo, um cursor de página que não é nosso. issues informa 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 — Nenhuma chave, ou uma chave errada ou revogada. A resposta não diz qual dos 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 de leitura. Toda chave criada hoje pode 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. Algo que pertence a outra conta recebe a mesma resposta.

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

amazon_not_connected · 409 — /targets, /ads e /reports/streaming-tv leem a Amazon no momento em que você pede, e a sua conta Amazon Ads não está conectada ou precisa ser reconectada. Resolva isso em Configurações → Amazon Ads, no Gloriads.

rate_limited · 429 — Um limite foi atingido. Espere o número de segundos indicado em Retry-After.

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

amazon_unavailable · 502 — A Amazon não respondeu a /targets, /ads ou /reports/streaming-tv, ou não conseguiu gerar o relatório de Streaming TV. Tente de novo em alguns minutos.

timeout · 504 — A resposta levou mais de 30 segundos. Peça menos coisas de cada vez.

Valores e páginas

• null significa “não existe”, nunca zero.
• Listas longas vêm em páginas. limit define o tamanho da página: de 1 a 100 (50 por padrão), ou até 1.000 (100 por padrão) para campanhas e grupos de anúncios. Quando has_more é true, envie next_cursor de volta como cursor para obter a próxima página.
• Uma página pode ter menos linhas que limit quando um filtro mantém poucas linhas (os grupos de anúncios de uma única campanha). Continue seguindo next_cursor até has_more ser false.