GlyphfieldErrors and limits
Handle validation responses, request limits, content types, and retries safely.
Validation failures use a structured response:
{
"error": {
"code": "invalid_request",
"field": "settings.width",
"message": "settings.width must be an integer between 64 and 4096."
},
"schemaVersion": 1
}Status codes
| Status | Meaning | Response |
|---|---|---|
| 400 | Malformed JSON or invalid field | Correct the named field |
| 413 | Request body exceeds 5 MB | Reduce or recompress embedded assets |
| 415 | Content-Type is not JSON | Send Content-Type: application/json |
| 429 | Production request rate limit exceeded | Wait for the limit window before retrying |
| 500 | Artifact generation failed | Log the response and retry only if appropriate |
Retry policy
Do not retry an unchanged validation request. Read error.field, correct the input, and submit a new request. Unknown top-level request fields fail with unknown_field rather than silently falling back to defaults.
For 429, stop concurrent work and wait for the rate-limit window. Do not fan out retries.
For transient 5xx responses, use bounded exponential backoff and retain the original request for diagnosis. Generation is deterministic for the same contract and inputs.
Important limits
- Request body: 5 MB maximum
- Data URL asset: 5 MB maximum
- Background width and height: 64–4096
- Background total pixels: 12,000,000 maximum
- Template title: 240 characters
- Template body: 1000 characters
- Remote asset URLs: unsupported
Contract drift
Always read GET /api/generate and check schemaVersion. If the schema version is unknown, stop and update the client rather than silently guessing.
Browser API failures
Browser automation uses JavaScript errors rather than HTTP status codes:
| Error | Typical cause | Response |
|---|---|---|
TypeError | Malformed action input, unsupported source, wrong control value, empty artifact | Correct the input; do not retry unchanged |
RangeError | Accessible control label or action is not exposed by the active adapter | Re-read describe() and controls(); confirm the active tool |
Error from a renderer | WebGL context, image decode, Canvas, GIF, MP4, font, or codec failure | Preserve source, capture the exact capability failure, retry only when conditions changed |
After a tool switch, the global adapter is replaced. A stale reference can report the old action set or mutate the wrong tool. Wait for glyphfield:studio-api-ready and re-read window.glyphfield.studio.
Do not swallow export errors and report success because the source was valid. A valid document and a rendered file are separate completion checkpoints.
Recovery-safe behavior
When rendering fails after source application:
- Re-read the source and retain it.
- Record
activeTool(),describe(), browser capability, requested format, dimensions, and action. - Stop sequence preview or release any active export job.
- Retry only after changing the actual failure condition.
- If the browser lacks the requested codec, report that limitation without substituting a different format.
For human-facing Studio, storage, WebGL, and export diagnosis, continue with Troubleshooting and recovery. For deployment abuse controls, see API security.