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 (100000/100000). Enable overage billing at https://szum.io/account/billing."
}Status codes
| Status | When | Where |
|---|---|---|
308 | Request URL had a query string on a path that doesn't accept one. Permanent redirect to the canonical path; clients should follow automatically | GET /c/{id}, GET /e/{id} |
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, PUT /api/charts/{id}/config, DELETE /api/charts/{id} |
403 | Feature requires a higher plan (e.g. themeOverrides on Free) | POST /chart, GET /c/{id}, GET /e/{id}, POST /api/charts |
404 | Saved chart was deleted or unpublished, never existed, or you don't own the chart addressed by a /api/charts/{id} endpoint | GET /c/{id}, GET /e/{id}, GET/PUT /api/charts/{id}[/config], DELETE /api/charts/{id} |
413 | Config exceeds 50 KB | POST /chart, POST /api/charts, PUT /api/charts/{id}/config, 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 /e/{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