Contents

Rate limit

The Cacoo API limits the number of requests each user can make in a minute. The limit applies to each of the following types.

Requests are counted in one-minute windows starting at second 0 of each minute, and the count is reset at the time in X-RateLimit-Reset. Requests refused for going over the limit are counted too.

Types and limits

Type	Requests per minute
Read	60
Write	30

The limits are the same for all plans.

Read

Write

They count as writes when called with GET too.

Not limited

The following requests are not subject to this limit.

Users
oEmbed
Getting the image of a public diagram without credentials (an API key, an access token, or being signed in to Cacoo)
The authentication and authorization endpoints (see Authentication & Authorization)

Response

Status line

When the number of requests exceeds the limit, the API server returns 429 (Too Many Requests) with the following JSON body, whatever the endpoint or the response format (.json, .xml or an image).

{
  "error": {
    "code": "rate_limited",
    "message": "Too many read calls. Retry after 12 seconds."
  }
}

Response headers

Responses to requests subject to the limit have the following headers. They may be missing from error responses, or while the count is temporarily unavailable; treat a response without them as one whose remaining count is unknown.

HTTP header	Content
X-RateLimit-Limit	The maximum number of requests per minute
X-RateLimit-Remaining	The number of requests left until the time in X-RateLimit-Reset
X-RateLimit-Reset	The time the count is reset (UNIX time)
X-RateLimit-Used	The number of requests in the current minute, this one included

A 429 response also has the following header.

HTTP header	Content
Retry-After	The number of seconds to wait before the next request

Example

The headers after 8 read requests in the minute from 9:00:00 JST on November 16, 2026. 52 more requests are allowed, and the count is reset at 9:01:00 JST on November 16, 2026 (UNIX time 1794787260).

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 52
X-RateLimit-Reset: 1794787260
X-RateLimit-Used: 8

Staying within the limit

To stay within the limit:

Do not send several requests at once from one piece of software. Send the next request after the response to the previous one.
When reading or writing many diagrams in a row, check X-RateLimit-Remaining, and when few requests are left, wait until the time in X-RateLimit-Reset.
When 429 is returned, retry after the number of seconds in Retry-After.
For software that runs regularly, such as a scheduled batch, cache the results of past requests to make fewer requests.

Do not use the API keys of several users from one piece of software to get around the limit.

Notes

The limit is per user, not per API key or application.

A user’s requests share the same limit whatever the authentication: API keys, OAuth applications, or a browser signed in to Cacoo. While one API key is limited, the user’s other API keys and applications are limited too.

Requests from integrations Nulab provides, such as the Google Docs add-on, count toward the same limit.