Limits and errors¶
Current TypeScript source limits¶
| Setting | Limit |
|---|---|
| Width | 1 to 16,384 pixels |
| Height | 1 to 16,384 pixels |
| DPI | 10 to 700 |
| Active queued renders | 1 per Express process |
| Request timeout configured in Express | 3,600 seconds |
These are implementation limits, not a promise that every accepted combination will succeed in a particular deployment. A 16,384 × 16,384 image contains more than 268 million pixels before renderer and post-processing overhead.
Common failures¶
| Symptom | Likely cause | Action |
|---|---|---|
404 for a render request |
Invalid or unknown WMS-VT key | Confirm the key through a secure channel. |
400 with validation errors |
Missing or malformed BBOX, dimensions, DPI, style URL, or attribution | Validate each parameter before retrying. |
400 for style URL |
Style could not be loaded or rendered | Fetch the style and all referenced assets from the rendering environment. |
| Missing labels or icons | Glyph or sprite request failed | Review style URL rewriting, provider access, and upstream responses. |
| Slow response | Queue wait, large output, cold cache, complex style, or slow upstream source | Reduce the test case and observe server/asset timing before retrying. |
| Wrong area | BBOX is in the wrong CRS or order | Send minX,minY,maxX,maxY in Web Mercator for the public route. |
Client behavior¶
- Set a timeout appropriate to the agreed output size.
- Retry only transient failures, with exponential backoff and jitter.
- Do not retry validation failures without changing the request.
- Limit concurrency at the caller.
- Record a request identifier if the service provides one in future.
- Verify the response content type before saving or embedding it.
Error payloads may evolve
Current handlers do not yet expose one versioned error schema for every failure path. Treat human-readable messages as diagnostic text rather than stable machine codes.