Errors

Handled Szum HTTP failures return an error object with a stable code, a human-readable message, and retryable. Chart findings appear once in diagnostics. MCP tool failures use the same fields inside their protocol response.

/validate is different: a completed check returns a validation result (valid, diagnostics, and optional compatibility and suggestedDocument), with HTTP 400 for an invalid chart or 413 over the input byte limit. Only a body that cannot be read uses the error object. The SDK returns completed validation results instead of throwing for an invalid chart.

An invalid chart sent to GET /chart returns:

{
  "error": {
    "code": "validation_failed",
    "message": "values.field: Field \"revenue\" is missing from 1 of 1 data row. Every referenced field must exist on every row.",
    "retryable": false
  },
  "diagnostics": [
    {
      "code": "incompatible_data",
      "severity": "error",
      "path": "/config/values/field",
      "relatedPaths": [],
      "message": "Field \"revenue\" is missing from 1 of 1 data row. Every referenced field must exist on every row.",
      "details": {
        "reason": "data_field_missing",
        "affectedRows": 1,
        "field": "revenue",
        "roles": ["value"],
        "rowCount": 1,
        "samplePaths": ["/data/0/revenue"]
      }
    }
  ]
}

Structured chart diagnostics

Use stable diagnostic code and path values for program behavior. Display the human-readable message; do not parse it. Messages may improve without changing the code contract.

Diagnostic paths are relative to the chart document. The outer document field of a saved-chart request body does not change them, so a finding keeps the same pointer across the SDK, HTTP, and MCP.

Errors block output. Warnings need explicit approval of the exact input in MCP render and write actions; HTTP requests proceed, so validate first if your product needs a review step. Suggestions are optional. A suggestedDocument is a complete, validated replacement; review it before using it, and validate again only if you change it. See validation for details.

The TypeScript SDK exposes chart findings as SzumError.diagnostics and retains the complete response as SzumError.failure. Error codes survive status-based subclass selection. Web and Figma clients parse the same generated contract. HTML embed error pages present the error message; successful images carry diagnostics in X-Chart-Diagnostics.

Status codes

Retry behavior

Do not retry 400, 401, 403, 404, or 413 without changing the request, credentials, ownership, or account state.

A failed image delivery releases its quota reservation, so a failed render is never charged.

retryable never authorizes replaying an ambiguous metered render or write. Operation-specific retry rules and Retry-After still apply. Network failures, responses generated by infrastructure, and OAuth or JSON-RPC errors from the framework may not contain a Szum error object, so clients need a fallback for them.

Retry 409 only after reading current state and resolving the conflict. For an idempotent create, reuse the same idempotency key and exact document rather than generating a new one.

Back off for 429 and honor Retry-After. Retry safe operations only for their documented transient failures, using a bounded policy. Do not automatically replay a metered render after a timeout, network failure, or gateway error: the first request may already have committed. The SDK retries metered renders only on 429.

Rate-limit and usage headers

429 responses include Retry-After when a concrete retry window exists. Authenticated render responses expose current usage information through X-Usage-* headers. Because those values are account-specific, authenticated responses are never public-cacheable.

Successful public images and embeds may be served from CDN without reaching origin. A CDN hit does not produce new origin usage headers or consume another render.

Compatibility failures

An older config that converts with losses returns compatibility.lossCodes: it can render, but a direct API or MCP write needs every code in acceptLosses, or it fails with loss_approval_required. An unsupported one returns compatibility.unsupportedCode, renders and writes nothing, and leaves stored charts unchanged. See older config compatibility for every code.

Common chart mistakes

• Sending only ChartConfig instead of a complete document with data.
• Omitting version, or using a different nested config version. The SDK fills in a missing version; raw HTTP does not.
• Using null for an optional property instead of omitting it.
• Referring to a field that is missing from any row.
• Using zero or negative values with a log scale.
• Giving a column, bar, or area value a log scale (only ranged columns and bars accept one), or ignoring the warning when an explicit value domain excludes zero.
• Repeating label content or wide-value fields.
• Putting output, size, or presentation inside config.
• Retrying a create with a new idempotency key, which creates a duplicate chart.
• Parsing an image response as JSON.

Validate the exact changed input once before rendering or writing. See Validation and compatibility for finding and fix semantics.

See also

• HTTP API
• Authentication
• Plans and limits