Grid82
grid82.comJoin the waitlist
DevelopersErrors

Errors and rate limits

Standard error codes, hidden-field guarantees, save warnings, payment vs rate limit semantics, and /v1 API rate limits.

Every error on the Builder API, App API, and MCP tools uses the same JSON envelope:

JSON
{
  "error": {
    "code": "forbidden",
    "message": "Your role does not allow updating this record.",
    "details": {}
  }
}

Switch on error.code in code; message text may improve over time.

Error codes

CodeHTTPMeaning
unauthenticated401Missing/invalid bearer token, or token issued for the wrong plane
forbidden403Role permissions or credential scopes reject this action
not_found404Resource missing, deleted, or outside your visible record scope
conflict409Concurrent modification (baseVersion/baseRevision) or reused Idempotency-Key
validation_failed422Malformed input, unknown key, invalid cursor, or invalid field type value
payment_required402Plan quota, workflow step cap, or AI credit balance reached (waiting won’t clear it)
rate_limited429Request rate ceiling reached (back off and retry)
not_implemented501Capability unavailable on this deployment
internal500Unexpected server error; safe to retry using the same Idempotency-Key

What errors never disclose

  • Invisible fields. Errors never confirm the existence of a hidden field. Referencing a hidden column in a query or write fails the exact same way as referencing a non-existent column.
  • Scoped records. Reading or updating a record hidden by a role filter returns 404 not_found, indistinguishable from a missing ID.

Successful writes with warnings

Email, URL, and phone columns preserve supplied strings verbatim, even when formatted unusually. Those writes succeed (200 / 201) and return a warnings array containing entries with recordId, fieldId, fieldName, and code: "suspect_format". Do not retry a write that returned warnings.

Rate limits

  • Auth and OAuth endpoints. Rate-limited per IP per minute (429 rate_limited).
  • /v1 REST API and /mcp. Rate-limited per credential at 1,200 requests per minute and 300 requests per 10 seconds (or 600 per minute per IP for unauthenticated calls). Exceeded limits return 429 rate_limited with a RateLimit-Policy response header.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search Grid82 documentation and read it in full, instead of answering from memory.

https://grid82.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://grid82.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.