Límites y errores

Límites de solicitudes

Ambos cuentan para toda la cuenta: todas tus claves y tus asistentes de IA conectados juntos.

• El límite por minuto se recarga de forma continua: se recupera una solicitud cada segundo, hasta 60.
• El límite diario es una ventana de 24 horas, no un día del calendario. El encabezado X-RateLimit-Reset-Day indica cuándo termina.

Encabezados de límite de uso

Cada respuesta a una solicitud con una clave válida lleva:

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

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

La forma de un error

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

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

Códigos de error

invalid_request · 400 — Un parámetro no es válido: un valor desconocido, un número fuera de rango, un cursor de página que no es nuestro. issues indica qué parámetro y por qué.

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

unauthorized · 401 — No hay clave, o la clave es incorrecta o está revocada. La respuesta no dice cuál de los dos casos es, a propósito.

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

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

not_found · 404 — No hay ningún endpoint en esta ruta, o lo que pediste no existe en tu cuenta. Algo que pertenece a otra cuenta recibe la misma respuesta.

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

amazon_not_connected · 409 — /targets, /ads y /reports/streaming-tv leen de Amazon en el momento en que lo pides, y tu cuenta de Amazon Ads no está conectada o hay que reconectarla. Corrígelo en Configuración → Amazon Ads, en Gloriads.

rate_limited · 429 — Se alcanzó un límite. Espera el número de segundos que indica Retry-After.

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

amazon_unavailable · 502 — Amazon no respondió a /targets, /ads o /reports/streaming-tv, o no pudo generar el informe de TV por streaming. Vuelve a intentarlo dentro de unos minutos.

timeout · 504 — La respuesta tardó más de 30 segundos. Pide menos cosas a la vez.

Valores y páginas

• null significa “no existe”, nunca cero.
• Las listas largas llegan por páginas. limit fija el tamaño de la página: de 1 a 100 (50 por defecto), o hasta 1000 (100 por defecto) para las campañas y los grupos de anuncios. Cuando has_more es true, envía next_cursor de vuelta como cursor para obtener la página siguiente.
• Una página puede tener menos filas que limit cuando un filtro conserva pocas filas (los grupos de anuncios de una campaña). Sigue next_cursor hasta que has_more sea false.