Skip to main content
Marble applies global rate limits to protect the stability of the API for all users. This page explains the limits, how they are calculated, and how to design your integration to handle them gracefully.

​
Overview

Marble API uses rate limiting to ensure fair usage and API stability. Rate limits are enforced per workspace using a sliding window approach.
Most applications will not hit these limits during normal use, but you should still build in defensive handling for rate limit responses.

​
Rate limit tiers

There are two rate limit tiers, depending on whether the request is associated with a workspace.

​
1. Workspace-scoped requests

All requests to workspace routes are rate limited per workspace:
  • Limit: 200 requests per 10 seconds
  • Applies to: All routes under /v1/:workspaceKey/*
    • GET /v1/:workspaceKey/posts
    • GET /v1/:workspaceKey/post/:slug
    • GET /v1/:workspaceKey/categories
    • GET /v1/:workspaceKey/tags
    • GET /v1/:workspaceKey/authors
This means each workspace can make up to 200 requests every 10 seconds before receiving 429 Too Many Requests responses.

​
2. Non-workspace requests (fallback)

For requests that are not associated with a workspace, a more conservative limit applies:
  • Limit: 10 requests per 10 seconds

​
Rate limit response headers

When rate limiting is active, responses include standard headers that let you understand how many requests you have remaining in the current window.
​
X-RateLimit-Limit
integer
The maximum number of requests allowed in the current window.
​
X-RateLimit-Remaining
integer
The number of requests remaining in the current window before you hit the limit.
​
X-RateLimit-Reset
integer
Unix timestamp (in seconds) when the current rate limit window resets.
You should use these headers to dynamically adjust your request rate, especially for background jobs and batch operations.

​
When you exceed the limit

If you exceed the allowed number of requests in the current window, the API returns a 429 Too Many Requests error. 
curl -i "https://api.marblecms.com/v1/YOUR_WORKSPACE_KEY/posts"

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1732389600

{
  "error": "Too many requests",
  "details": {
    "message": "You have exceeded the allowed number of requests. Please try again after the reset time.",
    "statusCode": 429
  }
}
If you receive 429 responses, you should back off immediately, respect the X-RateLimit-Reset header, and implement exponential backoff with jitter in automated clients.

​
Best practices

  • Reuse responses: Cache responses in your application where possible (for example, for blog pages or marketing sites) to avoid unnecessary repeated API calls.
  • Batch requests: For background jobs, group related work into fewer API calls instead of many small ones.
  • Monitor 429 rates: Track how often you see 429 responses and adjust your usage patterns if they become frequent.