Errors and rate limits

When the API refuses a request, it answers with an HTTP status and a JSON body that says why. This page lists the refusals a credential can get and explains the rate limit.

The error bodyCopy Anchor Link

Every error body is JSON with the reason in message. Some errors add more fields:

{ "message": "This API credential has expired" }

Credential refusalsCopy Anchor Link

The credential is checked on every request before anything else. A token in the edk_... form that does not authenticate gets 401, even on an operation that would otherwise be public. A bearer token that does not start with edk_ (lowercase) is not treated as a credential: on a public read it is served as an anonymous request, with no error.

The 401 headerCopy Anchor Link

Every 401 carries this header:

WWW-Authenticate: Bearer error="invalid_token"

Other statusesCopy Anchor Link

• Every operation can return 404 (not found), 429 (rate limited, below) and 500 (server error).
• Write operations can also return 409 when the change conflicts with the current state.
• Write operations can also return 422 when a field breaks a rule, for example a startsAt in the past or an endsAt before startsAt. The body carries errorCode SCHEDULE_INVALID and invalidFields.
• A create or update can also return 400 when it names something that does not exist or is not available to this organization: an unknown graphicsTemplateId on an update (the body carries invalidFields), or a tagIds entry on a create or update. A create that returns 400 for tagIds has already created the broadcast, so look it up before retrying.
• Bulk calls return 207 with one result per row. See Bulk operations.

If a 500 keeps happening, contact support and quote the reference from the error body when there is one.

Rate limitCopy Anchor Link

Each credential has its own rate limit: a burst of requests it can make at once, which refills over time.

By default a credential can make a burst of about 60 requests, refilling at about 120 per minute. Your platform's operator can change these, and you may occasionally be limited a little sooner or later than that, so always handle 429 rather than counting on an exact number.

What a request costsCopy Anchor Link

• A bulk call costs one request per entry in operations.
• Every other call costs one request, including a list read with limit=all.

The 429 responseCopy Anchor Link

Over the rate limit, a request gets 429 with a Retry-After header, in seconds, and this body:

{
  "message": "Too many requests from this API credential. Retry after 3 seconds.",
  "errorCode": "rate_limited",
  "retryAfterSeconds": 3
}

Wait that many seconds, then retry.

Retry after a rate limitCopy Anchor Link

url="$EVENTDOOR_API/organizations/acme/hubs/home-games/broadcasts"
for attempt in 1 2 3 4 5; do
  status=$(curl -s -D headers.txt -o body.json -w '%{http_code}' \
    -H "Authorization: Bearer $EVENTDOOR_TOKEN" "$url")
  [ "$status" != "429" ] && break
  wait=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
  sleep "${wait:-1}"
done
cat body.json

Retry only the request that got 429. Retrying a 4xx other than 429 without changing anything gets the same refusal.