Skip to main content

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)

json
{ "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

json
{ "error": "Invalid JSON in request body" }

URL too long (GET endpoint only)

json
{ "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 valueMeaning
typeRoot-level chart type; must be line, bar, pie, doughnut, radar, or polarArea
data.labelsThe labels array — must have 1–1000 entries
data.datasets.0.datadata array of the first dataset (index 0)
width / heightRoot-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 type or data — both are always required
  • Invalid chart type or format string — values are case-sensitive ("Line" fails, "line" works)
  • Dimensions outside 100–4000 px, or scale outside 1–4
  • Empty data.labels or data.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 chart or c GET parameter
  • An unknown type or cht in 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's usage array 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

json
{ "ok": true, "image_url": "https://cdn.example/charts/….png", "repairs_applied": false, "warnings": [], "normalized_config": { "type": "bar", "data": { "…": "…" } } }

Validation failure

json
{ "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

json
{ "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

json
{ "error": "Invalid API key" }

Malformed Authorization header

The header was present but did not start with Bearer (with the trailing space).

json
{ "error": "Invalid Authorization format. Use: Bearer <api_key>" }

No credentials on POST

json
{ "error": "Missing API key. Use Authorization: Bearer <key> header or ?key=<key> query param." }

Fix

CauseFix
Typo in keyCopy the key exactly from API Keys in your dashboard
Wrong prefix formatHeader must be Authorization: Bearer pk_live_… (note the space)
Key was deletedCreate a new key in the dashboard
POST sent with no credentialsAdd the header or ?key=; only GET has an anonymous tier
Using a pk_test_ key against production dataSandbox 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.

json
{ "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 (unlimited on Custom)
  • X-Quota-Used — used so far, including this request
  • X-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.

json
{ "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

featureFix
format:pdfUse PNG, SVG or WebP, or upgrade
resolutionKeep the longest edge (width or height × devicePixelRatio) within the plan's maximum (1200px on Free, 3000px on paid plans), or upgrade
api_keysRevoke an unused key, or upgrade
ai_rendersAI 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

json
{ "error": "Rate limit exceeded", "retryAfter": 120 }

Headers also present on 429 rate-limit responses:

  • Retry-After — Seconds until the window resets
  • X-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

CauseFix
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.

json
{ "error": "Internal server error" }

Email hello@chart-output.com with the X-Request-Id from the response header and we will investigate.