Rate limits, quotas, errors and retries
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
429with aRetry-Afterheader: 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.