Errors and status codes
One error shape, and every status code the API returns.
Every error returns the same JSON shape, with a machine-readable code and a human-readable message:
{ "error": { "code": "not_found", "message": "No chart with that id" } }
Branch on the code; show the message. The HTTP status matches the code.
Status codes
| Status | Code | When it fires |
|---|---|---|
| 401 | unauthorized | The key is missing, invalid, revoked, or the account no longer has API access. |
| 403 | insufficient_scope | The key is valid but was not granted the scope the endpoint requires. |
| 404 | not_found | No resource with that id in your workspace (charts, folders), or an unknown statistic id or source. |
| 422 | invalid_body | The request body is not a JSON object. |
| 422 | invalid_data | A CSV upload could not be parsed (needs a header row and at least one data column). |
| 422 | invalid_series_transform | meta.seriesTransform has an unknown function or a malformed op. |
| 422 | invalid_format | An export format other than png, svg, pdf, or csv. |
| 422 | invalid_folder / invalid_parent | A folder id (or parent) that is missing, in another workspace, or would create a cycle. |
| 422 | missing_source | Constructing a statistic without a source query param. |
| 422 | missing_dimension | A required dimension was omitted when constructing a statistic. The message names it. |
| 422 | invalid_selection | The dimension values do not resolve to a statistic. |
| 429 | rate_limited | Over the per-account rate limit. Retry after the Retry-After seconds. |
| 500 | export_failed | The renderer could not produce the file. |
| 503 | export_busy | Too many exports at once. Retry after Retry-After: 5. |