Error Reference

HTTP status codes and error responses returned by the API.

400 Bad Request

Invalid chart specification. Check the request body against the schema. Common causes:

Missing required fields (type, data)
Invalid chart type or format
Dimensions outside 100–4000 px
Too many labels, data points, or datasets
URL exceeds 2000 characters on GET endpoint
Invalid base64 encoding in the chart or c parameter

json

{
  "error": "Invalid chart specification",
  "details": [{ "path": "data.labels", "message": "At least 1 label is required" }]
}

401 Unauthorized

An Authorization header was present but the API key was invalid or malformed.

Important: Requests with no authentication at all return 200 at anonymous/starter plan limits — not 401. 401 is only returned when you send an invalid key, not when you omit auth entirely.

json

{ "error": "Invalid API key" }

402 Payment Required

Three distinct conditions return 402. Check the plan and error fields to determine which:

Monthly quota exceeded

json

{
  "error": "Monthly render quota exceeded",
  "currentUsage": 10000,
  "limit": 10000,
  "plan": "trial"
}

Trial expired

json

{
  "error": "Trial expired. Please upgrade to continue.",
  "plan": "expired",
  "upgradeUrl": "/app/usage-billing"
}

PDF format requires Pro plan

json

{
  "error": "PDF output requires the Pro plan",
  "plan": "starter",
  "upgradeUrl": "/app/usage-billing"
}

429 Too Many Requests

Rate limit exceeded. Default: 100 requests per 15-minute window per API key or IP. Check the Retry-After header before retrying.

json

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

Response headers included on 429:

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

500 Internal Server Error

Server error during rendering. Include the X-Request-Id response header when reporting issues to hello@chart-output.com.

json

{ "error": "Internal server error" }