Best Practices

Follow best practices to avoid being rate-limited and triggering unnecessary updates.

Rate Limits

Rate limits help ensure a consistent developer experience for all API users. By default, requests are limited to 60 requests every 30 seconds.

When a request has been rate-limited, it will return a TOO_MANY_REQUESTS error and send the following headers in response:

Header	Description
X-RateLimit-Requests-Limit	The number of requests allowed per window milliseconds.
X-RateLimit-Requests-Window	The time frame, in milliseconds, to keep track of requests.
X-RateLimit-Retry-After	The number of milliseconds to wait before retrying.

Size Limits

Pine also limits the size of input parameters and the overall request to a 256KB payload.

Property type	Limit
Depth of recursive Block editor inputs.	3 levels deep.
Arrays of Block or Inline editor inputs.	100 elements.
Inner Text string inputs	1000 characters.

For example, the following request would violate the depth, element, and character limits:

const client = new PineClient({ accessToken: "YOUR_TOKEN" });

const card = await client.cards.create.mutate({
  data: {
    title: [
      {
        // depth of 1
        type: "heading",
        heading: { color: "gray" },
        children: [
          // depth of 2
          {
            type: "heading",
            heading: { color: "gray" },
            children: [
              // depth of 3
              {
                type: "heading",
                heading: { color: "gray" },
                children: [
                  // depth of 4 (exceeds depth limit of 4)
                  {
                    type: "heading",
                    heading: { color: "gray" },
                    content: [
                      // element 1
                      { type: "text", text: { text: "..." } },
                      
                      // ...

                      // element 101 (exceeds element limit of 100)
                      {
                        type: "text",
                        text: {
                          // text (exceeds character limit of 1000 characters)
                          text: ".".repeat(1001)
                        }
                      }
                    ],
                    children: []
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
    // ...
  }
});

These limits only apply to requests sent to Pine's API. Responses returned by the API do not have these limits.