Error Reference
Every error code the API returns, what caused it, and exactly how to fix it. Every JSON body below is verbatim from the production handler.
All error responses include an X-Request-Id header. Include it when contacting hello@chart-output.com.
400 Bad Request
The request body is not valid JSON, or the chart spec fails schema validation. The details array always identifies the exact failing field — no guessing required.
Invalid chart specification (Zod validation failure)
{
"error": "Invalid chart specification",
"details": [
{ "path": "data.labels", "message": "At least 1 label is required" },
{ "path": "width", "message": "Number must be less than or equal to 4000" }
]
}Malformed JSON in request body
{ "error": "Invalid JSON in request body" }URL too long (GET endpoint only)
{
"error": "URL too long",
"message": "URL exceeds 2000 characters. Use POST for complex charts."
}Reading details[].path
Each path uses dot notation and maps directly to a key in your JSON spec. Array indices appear as numbers.
| path value | Meaning |
|---|---|
| type | Root-level chart type; must be line, bar, pie, doughnut, radar, or polarArea |
| data.labels | The labels array — must have 1–1000 entries |
| data.datasets.0.data | data array of the first dataset (index 0) |
| width / height | Root-level dimensions; must be integers in the range 100–4000 |
| (empty string) | Error is at the root of the spec — usually a missing required field |
Common causes
- Missing
typeordata— both are always required - Invalid chart type or format string — values are case-sensitive (
"Line"fails,"line"works) - Dimensions outside 100–4000 px, or
scaleoutside 1–4 - Empty
data.labelsordata.datasets, or more than 1000 labels / 20 datasets / 1000 data points per dataset - Trailing commas or single-quoted strings — standard JSON only
- Non-HTTPS
header.logoUrl— only HTTPS URLs are accepted - Invalid base64 encoding in the
chartorcGET parameter - An unknown
typeorchtin GET query parameters — the request is refused rather than drawn as a line chart - Google Image Charts parameters on GET (
cht=bvs,chd=t:…,chs,chl, …) — Chart Output doesn't read Google's URL format; the response'susagearray shows the two forms it does read
Fix
Read details[].path and details[].message. Every field name is a direct reference to your spec JSON. The Chart Studio playground highlights the offending key inline.
repair_mode structured envelope
When you set repair_mode to off or safe on /api/v1/render or /api/v1/ai/render, success and validation failures use a shared JSON envelope instead of raw image bytes. Omitting repair_mode keeps the legacy response shape.
Success
{
"ok": true,
"image_url": "https://cdn.example/charts/….png",
"repairs_applied": false,
"warnings": [],
"normalized_config": { "type": "bar", "data": { "…": "…" } }
}Validation failure
{
"ok": false,
"error": {
"code": "LABEL_DATA_LENGTH_MISMATCH",
"path": "/data/datasets/0/data",
"message": "Dataset 0 has 2 values but labels has 3 entries.",
"retryable": true,
"requires_decision": true,
"suggested_fix": "Make data.labels.length match every dataset data.length…",
"details": { "labelCount": 3, "datasetCount": 2 }
}
}AI generation failure
{
"ok": false,
"error": {
"code": "GENERATION_FAILED",
"path": "",
"message": "Model returned output that was not valid JSON",
"retryable": true,
"requires_decision": false
}
}Common codes: LABEL_DATA_LENGTH_MISMATCH, INVALID_COLOR, DUPLICATE_TIMESTAMPS, CONFLICTING_SCALE_SYNTAX, TIME_ADAPTER_REQUIRED, NEGATIVE_VALUE_IN_PART_TO_WHOLE_CHART, INVALID_SCALE_TYPE, GENERATION_FAILED.
401 Unauthorized
Either an Authorization header was present but the key was invalid, malformed, or revoked — or the request was a POST with no credentials at all.
Omitting auth entirely is method-dependent: on GET /api/v1/render it returns 200 on the anonymous plan (PNG only, 1200px max, 5 requests per 15 minutes per IP). On POST /api/v1/render it returns 401 — there is no anonymous POST tier. See Authentication for the full comparison.
Invalid or revoked API key
{ "error": "Invalid API key" }Malformed Authorization header
The header was present but did not start with Bearer (with the trailing space).
{ "error": "Invalid Authorization format. Use: Bearer <api_key>" }No credentials on POST
{ "error": "Missing API key. Use Authorization: Bearer <key> header or ?key=<key> query param." }Fix
| Cause | Fix |
|---|---|
| Typo in key | Copy the key exactly from API Keys in your dashboard |
| Wrong prefix format | Header must be Authorization: Bearer pk_live_… (note the space) |
| Key was deleted | Create a new key in the dashboard |
| POST sent with no credentials | Add the header or ?key=; only GET has an anonymous tier |
Using a pk_test_ key against production data | Sandbox keys work for renders; they are not restricted by environment |
402 Quota exceeded
The account has used its allowance for this billing period. Nothing is rendered and nothing is counted. Free resets on the 1st of each month (UTC); paid plans reset with the Stripe billing period.
{
"error": "quota_exceeded",
"message": "You have used 1,000 of 1,000 renders this period on the free plan.",
"metric": "renders",
"limit": 1000,
"used": 1000,
"plan": "free",
"resets_at": "2026-12-01T00:00:00.000Z",
"upgrade_url": "https://www.chart-output.com/billing/upgrade?plan=pro"
}metric is renders for render requests and ai_renders for /api/v1/ai/render. Every successful metered response carries the same numbers as headers:
X-Quota-Limit— allowance for the period (unlimitedon Custom)X-Quota-Used— used so far, including this requestX-Quota-Reset— ISO 8601 time the allowance resets
Fix
Open upgrade_url to move to a larger plan (the new limit applies as soon as checkout completes), or wait for resets_at.
403 Plan required
The API key is valid but the request uses something the current plan does not include. required_plan names the cheapest plan that does.
{
"error": "plan_required",
"message": "PDF output needs the Pro plan. Your Free plan includes PNG, JPEG, SVG, WEBP.",
"feature": "format:pdf",
"plan": "free",
"required_plan": "pro",
"upgrade_url": "https://www.chart-output.com/billing/upgrade?plan=pro"
}Fix
feature | Fix |
|---|---|
format:pdf | Use PNG, SVG or WebP, or upgrade |
resolution | Keep the longest edge (width or height × devicePixelRatio) within the plan's maximum (1200px on Free, 3000px on paid plans), or upgrade |
api_keys | Revoke an unused key, or upgrade |
ai_renders | AI rendering is on paid plans |
429 Too Many Requests
Per-window rate limiting. Running out of your plan's allowance is a 402, not a 429.
Rate limit — 100 requests per 15 minutes
{
"error": "Rate limit exceeded",
"retryAfter": 120
}Headers also present on 429 rate-limit responses:
Retry-After— Seconds until the window resetsX-RateLimit-Limit— Maximum requests per window (100)X-RateLimit-Remaining— Requests remaining (0 on 429)X-RateLimit-Reset— ISO 8601 timestamp of when the window resets
Fix
| Cause | Fix |
|---|---|
| Rate limit (100/15 min) | Wait Retry-After seconds, or distribute requests over time |
500 Internal Server Error
Server error during rendering. This is never caused by your spec — it means something went wrong on our side.
{ "error": "Internal server error" }Email hello@chart-output.com with the X-Request-Id from the response header and we will investigate.