Limits and errors
The API works within the limits of your plan, the same ones the editor has. When a request is refused, the answer carries an error code that links to its entry on this page.
On this page
What each plan gets
The API is part of every plan, Free included.
| Limit | Free | Pro |
|---|---|---|
| Saved charts | 5 | No limit |
| Requests a minute | 60 | 60 |
| Saved charts rendered as they are, a day | 100 | 2,000 |
| Image renders a month: each different picture from the image calls and image links | 100 | 1,000 |
| Times a day an account's image links are drawn, counted or not | 1,000 | 10,000 |
| chartjuice.com mark on images | Yes | No |
| Save a brand palette | No | Yes |
| Website color lookups a day | None | 20 |
| API keys | 10 | 10 |
| Image signing keys | 3 | 3 |
There are two counts for images:
- Rendering a saved chart as it is, which is what an assistant does when it looks at its work, is counted by the day.
- Drawing a chart from data that is not saved in it is an image render, and those are counted by the calendar month. That covers a chart drawn from a definition, a saved chart drawn with other data, and the picture an image link shows.
Days and months are in UTC.
An image render is counted once for each different picture in a month. Ask for the identical image twice and the second costs nothing, whichever call or link asked for it. A link counts once each time its chart changes, and once at the start of each month. A drawing that fails is not counted, in either count. For example, a chart that you update every Monday and link from a newsletter uses one image render at the start of the month and one for each Monday's update, however many people open the newsletter.
Image renders are counted once for the account that pays for the plan. Teammates on a Pro seat draw from the owner's count and do not get one of their own.
Because opening a link again costs you nothing, two more limits keep someone else from asking for your links without end. An account's links are drawn only so many times a day, and answer only so many requests a minute. Past either, they show "Chart unavailable" for a while and then work again. Readers of a page or an email do not come near these numbers, because a picture is kept for a few minutes after it is drawn. They are in the tables below.
Requests are counted by the minute. Get the account to see what is left of each count. Chart images explains image links and the image calls.
Rate limits
When you pass the requests-a-minute limit, the answer is rate_limited with a Retry-After header: the number of seconds until the minute ends and you can send again. Requests that were refused do not count against you.
Every answer carries three headers that say where you stand: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, which is in seconds.
Size limits
| What | Limit |
|---|---|
| Request body | 5.5 MB |
| A saved chart, data included | 4 MB |
| Data read from CSV, TSV or JSON | 5,000 rows and 50 columns; the rest is left out, and the answer says so. JSON rows with more than 50 different keys between them are refused |
| Data after a step | 250,000 rows, 500 columns and 1,000,000 values; a step that would make more is refused |
| A rendered image | 4,000 px on each side, after the scale is applied |
| What an image is drawn from | 100 series, and about 20,000 bars, points, slices or cells |
| Time to draw an image | 8 seconds; a chart that takes longer is refused as too complex |
| Data carried in an image link | 4,000 characters once encoded, about 3,000 characters of CSV |
| How long a linked image is kept before it is drawn again | 5 minutes, or until the link expires if that is sooner |
| Requests to one account's image links | 600 a minute; after that its links show "Chart unavailable" until the minute ends |
| Requests with a key that is not valid, or image links that do not verify | 30 a minute from one network; after that, requests from it without a valid key or link wait out the minute |
Known limits
Images made by the API, image links included, draw text in the Latin, Greek and Cyrillic alphabets for now. Text in other scripts, such as Chinese, Japanese, Korean, Arabic, Hebrew or Thai, and emoji, comes out as empty boxes in the image. The chart is still saved correctly and looks right in the editor, where you can download it yourself.
Error codes
A refused request answers with one of these codes. The HTTP status it comes with is shown beside each.
invalid_requestHTTP 400
Something in the request is wrong: a field is missing or misspelled, a value is out of range, the body isn't JSON, or the chart can't be drawn as an image because it is too large or has too much in it. The message says which.
What to do: Fix what the message names and send the request again. Unknown fields are refused, so check spelling.
invalid_opsHTTP 400
One of the ops you sent isn't valid, so none of them were applied and the chart is unchanged. The message says which op and why, and lists the columns you can use when a column id is wrong.
What to do: Correct that op and send the whole list again. Chart edits has every op and its fields.
forbidden_planHTTP 403
This needs the Pro plan. Saving a brand palette and reading colors from a website are Pro features.
What to do: Upgrade the account to Pro, or leave this step out. Pricing has the plans.
not_foundHTTP 404
There's no chart with that id in this account, or no endpoint at that address. A chart in someone else's account gets this answer too.
What to do: List your charts to get the ids you can use, and check the address against the endpoint reference.
conflictHTTP 409
The chart changed after you last read it, so your edit was not applied. This happens when you send expected_updated_at and someone has saved the chart since, in the editor or through the API.
What to do: Get the chart again, look at what changed, and send your edit with the new updated_at.
chart_limit_reachedHTTP 409
The account is on the Free plan and already has as many saved charts as Free allows, so a new chart or a copy cannot be saved. Charts it already has can still be edited.
What to do: Delete a chart you no longer need, or upgrade to Pro for unlimited saved charts.
too_largeHTTP 413
The request body is too big to read, or the chart would be too big to save once the change is made.
What to do: Send fewer rows or columns. To chart a large file, total it or filter it first.
rate_limitedHTTP 429
Too many requests in a short time. The usual cause is passing the requests-a-minute limit. Too many requests with a bad key from one network, too many website color lookups in a day, or too many images being drawn at the same moment give the same answer. So does an image link when the links of its account are asked for far more often than readers would ask.
What to do: Wait the number of seconds in the Retry-After header, then try again. Space requests out if this happens often.
render_limit_reachedHTTP 429
The account has rendered as many images today as its plan allows. The count starts again at midnight UTC.
What to do: Wait the number of seconds in the Retry-After header, or upgrade to Pro for a higher daily allowance.
image_limit_reachedHTTP 429
The account has used its image renders for this calendar month, and the image asked for is one it has not drawn this month. The image API counts each different picture once a month, whether it is a chart drawn from a definition, a saved chart drawn with new data or an image link. It is one count for the account that owns the plan: teammates on a Pro seat share it. The count starts again on the 1st of the month, UTC, and the message names the day.
What to do: Wait for the 1st, or upgrade to Pro for a larger monthly allowance. Pictures already counted this month can still be drawn. Rendering a saved chart as it is has its own daily count and still works. Chart images explains how renders are counted.
internalHTTP 500
Something went wrong on our side. The request was not carried out, or we could not confirm that it was.
What to do: Try again in a moment. If it keeps happening, write to support@chartjuice.com and say what you were doing.