Errors
Status codes, response shape, and what each one means across the Szum API surface.
Failed JSON API operations return the standard error envelope: a JSON body with a single error field, paired with a meaningful HTTP status code. Public chart-delivery routes use the same status semantics and an explicit no-store error policy, but request-attribution, burst-limit, and embed-render failures may use a plain-text body. This page is the canonical transport-error reference – per-route docs link here instead of duplicating tables.
Chart validation has a richer read-only response with errors, complete diagnostics, and an optional suggestedConfig. See Validation and Review for that contract and POST /validate for the endpoint.
Response shape
{ "error": "marks.0.type: Invalid discriminator value" }Config-validation messages include a path when one is available. 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 (25000/25000). 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}, GET /r/{id} |
400 | Invalid JSON or query input, missing required config fields, structural validation failure, or a semantic error that prevents compilation | Config-accepting and parameterized routes |
401 | Missing or invalid credentials on an authenticated route | Authenticated POST /chart and /api/charts routes |
403 | Feature requires a higher plan (e.g. themeOverrides on Free) | GET/POST /chart, GET /r/{id}, POST /api/charts, PUT /api/charts/{id}/config |
404 | A saved or transient chart is unavailable, or you don't own the chart addressed by a /api/charts/{id} endpoint | GET /c/{id}, GET /e/{id}, GET /r/{id}, GET/PUT /api/charts/{id}[/config], DELETE /api/charts/{id} |
409 | An update would discard unpublished Studio changes; publish or discard them before retrying | PUT /api/charts/{id}/config |
413 | Config exceeds 50 KB or the account's saved-storage cap | GET/POST /chart, POST /api/charts, PUT /api/charts/{id}/config |
429 | Burst rate limit or monthly render limit exceeded. Includes a Retry-After header (seconds) | HTTP render endpoints and rate-limited chart-management routes |
500 | Render or internal operation failed | Render and chart-management routes |
502 | Bulk deletion could not enqueue every chart | DELETE /api/charts |
503 | A credential or storage dependency is temporarily unavailable. Includes Retry-After when a retry delay is known | Authenticated chart routes, GET /c/{id}, GET /e/{id}, and GET /api/charts/{id}/config |
Rate-limit headers
HTTP 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 – saved-chart publication and error lifecycle
- Plans & Limits – what triggers
429on the monthly bucket