IsoDelve

Home › Developer guide › Rate limits, quotas, errors and retries

Rate limits, quotas, errors and retries

Developer guide · updated

Two sets of numbers: today and at launch

The API is in a test phase. Free keys are self-serve (create a free account) and no one is billed. The limits the code enforces today are placeholders; the launch plans on the pricing page are what the paid service will use.

Launch plans (announced, not live yet):

Plan Maps a month Price Use
Free 1,000 $0 Personal
Hobby 15,000 $5/mo or $50/yr Personal
Creator 50,000 $15/mo or $150/yr Commercial with a credit line; optional overage $0.40 per 1,000
Business 250,000 $49/mo or $490/yr Apps, VTTs, bots; overage $0.20 per 1,000
Platform Custom from about $199/mo Contact us

Enforced today (placeholders in the API code):

Limit Free keys Pro keys Test (dev) keys
Largest map side 40 cells 64 cells 64 cells
Generate calls per minute 10 30 600
Fresh PNG renders per minute 5 20 600
Fresh PNG renders per month 50 2,000 unlimited
Largest PNG scale 0.5 1 1
Maps per month not capped yet not capped yet not capped yet

Monthly counters reset at the start of each calendar month in UTC. Check yours at any time with GET /v1/usage.

How the per-minute limits work

  • Each key has a sliding 60-second window per action (generate, render).
  • When you’re over, the API answers 429 with a Retry-After header: the number of seconds until a slot frees up.
  • Cache hits on PNGs never count. Pack downloads are not rate limited per key, but please cache them (they never change).
  • The limiter currently runs in memory on each API instance, so treat the numbers as approximate.
HTTP/1.1 429 Too Many Requests
Retry-After: 12
{"error":{"code":"rate_limited","message":"generate limit 10/min"}}

Every error code

All errors have the same shape: {"error":{"code":"…","message":"…"}}, plus field when one input is to blame.

Status code When What to do
400 bad_json Body isn’t valid JSON Fix the JSON
400 bad_request A parameter is out of range or unknown (field says which) Fix that field; don’t retry unchanged
400 pack_not_found pack names a pack that doesn’t exist Use GET /v1/packs
401 unauthorized Missing, malformed, unknown or revoked key Send Authorization: Bearer iso_… with a valid key
402 allowance_exceeded Monthly render allowance used Wait for next month or draw it yourself
403 plan_limit A PNG scale above your plan Use a smaller scale
404 map_not_found Wrong map id, or the map belongs to another key Use the key that created the map
404 pack_not_found GET /v1/packs/{ref} for an unknown pack Check the id and version
404 not_found Unknown route, or a pack file that isn’t served (models, missing previews) Check the URL
413 too_large Request body over 16 KB Send only the parameters you need
422 generation_failed The generator couldn’t satisfy the request (issues lists why) Try another seed, a bigger map or fewer rooms
422 pack_incomplete The pack lacks a piece the map needs Use a newer pack version
422 pack_not_found A stored map’s pack is no longer available for rendering Regenerate with a current pack
429 rate_limited Over a per-minute limit Wait Retry-After seconds
500 internal Our bug Retry once later; tell us if it repeats

Retrying safely

Retry only 429, 500 and network errors. Every other error will fail the same way again.

Note that POST /v1/maps stores a new map on every success. If a request times out after the server finished, a retry creates a second map; that costs a map from your quota but does no harm, because the same seed and settings produce the same dungeon.

async function isodelve(path, init = {}, tries = 4) {
  for (let attempt = 1; ; attempt++) {
    let res;
    try {
      res = await fetch("https://api.isodelve.com" + path, {
        ...init,
        headers: { Authorization: `Bearer ${process.env.ISODELVE_KEY}`, "Content-Type": "application/json", ...init.headers },
      });
    } catch (e) {
      if (attempt >= tries) throw e;                                   // network error
      await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt)); continue;
    }
    if (res.ok) return res;
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= tries) {
      const { error } = await res.json().catch(() => ({ error: { code: "http_" + res.status } }));
      throw Object.assign(new Error(error.message ?? error.code), error, { status: res.status });
    }
    const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt;  // seconds
    await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250));
  }
}

const map = await (await isodelve("/v1/maps", { method: "POST", body: JSON.stringify({ seed: "crypt-7" }) })).json();

The same in Python:

import json, os, random, time, urllib.error, urllib.request

def isodelve(path, body=None, tries=4):
    for attempt in range(1, tries + 1):
        req = urllib.request.Request("https://api.isodelve.com" + path,
            data=None if body is None else json.dumps(body).encode(),
            headers={"Authorization": "Bearer " + os.environ["ISODELVE_KEY"], "Content-Type": "application/json"})
        try:
            with urllib.request.urlopen(req) as r:
                return json.load(r)
        except urllib.error.HTTPError as e:
            if not (e.code == 429 or e.code >= 500) or attempt == tries:
                raise
            wait = float(e.headers.get("Retry-After") or 2 ** attempt)
        except urllib.error.URLError:
            if attempt == tries:
                raise
            wait = 2 ** attempt
        time.sleep(wait + random.random() / 4)

map_ = isodelve("/v1/maps", {"seed": "crypt-7"})

Staying inside your quota

  • Keep the JSON instead of generating the same map twice. Maps never change.
  • Draw maps yourself from the pack (Drawing a map) instead of asking for server PNGs.
  • Request PNGs at the smallest scale you need; repeated requests for the same image are free cache hits.
  • Generate on demand, not ahead of time “just in case”.

Next: Caching and attribution.