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; there are no issues or duplicate errors arrays. MCP tool failures use the same fields inside their protocol response.

/validate returns a validation result when the check completes: valid, diagnostics, and optional compatibility and suggestedDocument. Invalid chart input retains HTTP 400 (or 413 for the input byte limit). Failures to read the HTTP body use the operational error envelope. The SDK distinguishes these shapes and returns completed validation results instead of throwing for an invalid chart.

{
  "error": {
    "code": "validation_failed",
    "message": "Field \"revenue\" is missing from the data.",
    "retryable": false
  },
  "diagnostics": [
    {
      "code": "incompatible_data",
      "severity": "error",
      "path": "/config/values/field",
      "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. A saved-chart HTTP body's outer document field does not change those paths, so the same finding keeps the same pointer across the SDK, HTTP and MCP.

Errors block output. MCP render and write actions require explicit approval for warnings on the exact input; raw HTTP callers decide their own non-blocking-warning policy after validation. Suggestions remain optional. A suggestedDocument is a complete, validated replacement. Review the proposed changes before using it; validate again only if you modify it.

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.

Automatic sizing stops growing at 4096 logical pixels per axis and retains all source data. It no longer produces an Auto-overflow error. Explicit size validation remains separate. Failed image delivery still releases its temporary quota reservation.

retryable never authorizes replaying an ambiguous metered render or write. Operation-specific retry rules and Retry-After still apply. Browser/network failures, infrastructure-generated responses, and framework-owned OAuth or JSON-RPC errors may not contain a Szum envelope; clients retain a safe fallback for these boundaries.

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

Conversion failures for older configs use stable results:

• lossy returns stable compatibility.lossCodes; preview may proceed with diagnostics, while a direct API/MCP write of the older config requires explicit acceptance of every code;
• unsupported returns compatibility.unsupportedCode, performs no render or write, and leaves the stored chart unchanged.

See older config compatibility for the supported chart mappings and complete code lists.

Common chart mistakes

• Sending config without the data required by its roles.
• Sending an unversioned envelope instead of a complete document.
• Omitting the current version in raw HTTP JSON.
• Using null for an optional property instead of omitting it.
• Referring to a field that is missing from every row.
• Using zero or negative values with a log scale.
• Giving column, bar, or area an unsupported log value scale, or ignoring the warning from an explicit value domain that excludes zero.
• Repeating label content or wide-value fields.
• Sending output or size policy inside semantic config.

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