Errors
Status codes, response shape, and what each one means across the szum API surface.
Every szum endpoint returns the same error envelope: a JSON body with a single error field, paired with a meaningful HTTP status code. This page is the canonical reference – per-route docs link here instead of duplicating tables.
Response shape
{ "error": "marks.0.type: Invalid discriminator value" }The error message contains a path. marks.0.type means "the type field of the first mark." Use it to jump straight to the offending field instead of diffing the whole config.
For rate-limit and overage errors, the message also tells you what to do:
{ "error": "Monthly render limit exceeded. Enable overage billing at szum.io/dashboard/billing." }Status codes
| Status | When | Where |
|---|---|---|
400 | Invalid JSON, missing version/format, or schema validation failure | All endpoints |
401 | Missing or invalid API key on a key-required route | POST /chart, POST /api/charts, DELETE /api/charts/{id} |
403 | Feature requires a higher plan (e.g. themeOverrides on Free), or saved chart is paused (creator downgraded, in 30-day grace) | POST /chart, GET /c/{id}, POST /api/charts |
404 | Saved chart was deleted, never existed, or its grace period expired | GET /c/{id}, DELETE /api/charts/{id} |
413 | Config exceeds 50 KB | POST /chart, POST /api/charts, GET /chart |
429 | Burst rate limit or monthly render limit exceeded. Includes a Retry-After header (seconds) | All render endpoints |
500 | Render failure | POST /chart, GET /chart, GET /c/{id}, GET /r/{id} |
Rate-limit headers
429 responses include Retry-After (in seconds) so clients know how long to wait. The TypeScript SDK surfaces this as SzumError.retryAfter.
Successful POST responses also carry monthly usage headers – see API → Response.
Common config mistakes
The most common 400 causes – missing version, missing format, wrong mark type, mismatched field names, mixed sizing modes, unquoted JSON in GET URLs – are documented at API → Common mistakes.
See also
- API –
POST /chartandGET /chartreference - Saved charts –
403/404lifecycle on/c/{id} - Plans & Limits – what triggers
429on the monthly bucket