Errors & rate limits

Two error shapes

Everything except form submission returns a single error string:

{ "error": "Not found" }

Form endpoints return an ok flag as well, because a 201 can also mean “silently discarded” and a validation failure needs to name every field at once:

{
  "ok": false,
  "error": "Validation failed",
  "errors": [
    { "field": "email", "message": "email must be a valid email address" }
  ]
}

Some errors carry an extra code key: token_invalid, token_expired, submitted_too_fast on form submission, and the plan codes below. When a code is present, branch on it rather than on the message text; messages are written for people and may be reworded.

Status codes

Telling 404s apart

A 404 means one of several things, and the body is what distinguishes them.

Plan-related responses

Every workspace is on a plan, which caps how many of certain resources it may have: collections, forms and user accounts. The current plan, its caps and your usage against them are all shown on the billing screen in the dashboard; they are not readable over the API and are deliberately not printed here, because they are set per-workspace and would go stale on a static page.

Two codes appear on authenticated dashboard surfaces when the plan is the reason something failed. Both are 402, never 403, because a 403 would be indistinguishable from a feature being switched off, which paying cannot resolve.

Identity codes

Identity is a per-workspace beta. These appear on the public /api/v1/accounts/* endpoints and on the dashboard account-management surfaces:

Hosting codes

Hosting is a per-workspace beta, Pro and up. These appear on /api/dashboard/sites/*, reached through the sedgemark CLI:

AI-field codes

AI-populated fields is generally available and billed to the tenant's own provider key, which shapes several of these. See the Callout below.

Rate limits

100 requests per minute, per IP address , shared across three surfaces:

• /api/v1/*: the whole delivery API, including media and forms
• /api/mcp
• /api/dashboard/sdk

The budget is shared, not per-endpoint: MCP traffic and delivery traffic from the same address draw on the same 100. Over the limit you get:

HTTP/1.1 429 Too Many Requests

{ "error": "Too many requests" }

The window is a fixed minute that starts at your first request, not a rolling one.

Planning around it

• A browser form submit costs up to three requests : the descriptor GET at page load, an OPTIONS preflight (a JSON POST is never CORS-simple), then the POST itself. Preflights are cached for 24 hours per origin, and the descriptor fetch is only needed when the form has a min_submit_seconds requirement, so a repeat visitor to a form with no timing requirement costs one.
• Page with a large limit. Draining a 1,000-entry collection at limit=200 costs 5 requests; at limit=50 it costs 20. 200 is the maximum.
• Build, do not fetch per visitor. A static build reads your content once at build time from one machine. Fetching on every page view puts your visitors’ traffic against this limit.
• Shared addresses share the budget. Everyone behind one office NAT or one CI runner looks like a single caller.

A minimal backoff, which is all a build script needs:

async function sedgemarkFetch(url, init, attempt = 0) {
  const res = await fetch(url, init)

  // 429 is the only status worth retrying blindly. 4xx will not become 2xx.
  if (res.status === 429 && attempt < 4) {
    const wait = 2 ** attempt * 1000
    await new Promise((r) => setTimeout(r, wait))
    return sedgemarkFetch(url, init, attempt + 1)
  }

  return res
}

What is safe to retry

Every endpoint on the public API except form submission is a GET, so retrying is free of consequences. Retry 429 with backoff and 500 once; never retry a 400, 401, 403, 404 or 413 unchanged, since none of them will become a success on their own.

Form submission is not idempotent: a retry after a successful 201 stores a second submission. Retry it only on 429, on a network failure with no response, or on the two retryable anti-spam codes.