API & AI assistants/Limits and errors

Limits and errors

The Gloriads API's request limits and rate-limit headers, the shape of an error and what every error code means, and how values and pages work.

Request limits

LimitValue
Per minute60 requests
Per day10,000 requests

Both count for the whole account: all your keys and connected AI assistants together.

  • The minute limit refills continuously: one request comes back every second, up to 60.
  • The daily limit is a 24-hour window, not a calendar day. The X-RateLimit-Reset-Day header says when it ends.

Rate-limit headers

Every answer to a request with a valid key carries:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute (60)
X-RateLimit-RemainingRequests left right now
X-RateLimit-ResetSeconds until the minute limit is full again
X-RateLimit-Limit-DayRequests allowed per day (10,000)
X-RateLimit-Remaining-DayRequests left today
X-RateLimit-Reset-DaySeconds until the daily window ends

When a limit is reached, the answer is 429 rate_limited with a Retry-After header: wait that many seconds, then send the request again.

Every answer, error or not, also carries X-Request-Id.

The shape of an error

Errors follow the standard "problem details" format (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"
}
  • Test code in your script. It never changes; detail is written for people and may be reworded.
  • issues lists each invalid parameter. It only appears on invalid_request.
  • Quote request_id when you contact support.

Error codes

invalid_request · 400 — A parameter is not valid: an unknown value, a number out of range, a page cursor that is not ours. issues says which parameter and why.

api_key_in_query · 400 — The key was sent in the URL. Send it in the Authorization header, and revoke that key: it may already be in a log.

unauthorized · 401 — No key, or a key that is wrong or revoked. The answer does not say which, on purpose.

subscription_inactive · 403 — The account's subscription has ended. The API works again as soon as the subscription is active.

insufficient_scope · 403 — The key is not allowed to read. Every key created today can read, so you should never see this code.

not_found · 404 — There is no endpoint at this path, or the thing you asked for does not exist in your account. Something that belongs to another account gets the same answer.

method_not_allowed · 405 — The API only answers GET, because it is read-only. The Allow header lists what it accepts.

amazon_not_connected · 409 — /targets, /ads and /reports/streaming-tv read Amazon at the moment you ask, and Amazon Ads is not connected or needs to be reconnected. Fix it in Settings → Amazon Ads, in Gloriads.

rate_limited · 429 — A limit is reached. Wait the number of seconds in Retry-After.

internal_error · 500 — Something failed on our side. Try again later; if it keeps happening, send us the request_id.

amazon_unavailable · 502 — Amazon did not answer /targets, /ads or /reports/streaming-tv, or could not make the Streaming TV report. Try again in a few minutes.

timeout · 504 — The answer took longer than 30 seconds. Ask for less at a time.

Values and pages

  • null means "does not exist", never zero.
  • Long lists come in pages. limit sets the page size: from 1 to 100 (50 by default); up to 1,000 (100 by default) for campaigns, ad groups, targets and ads; up to 500 (100 by default) for an operation's lines. When has_more is true, send next_cursor back as cursor to get the next page.
  • A page can be shorter than limit when a filter keeps few rows (one campaign's ad groups). Keep following next_cursor until has_more is false.