---
title: "Errors and rate limits"
description: "Standard error codes, hidden-field guarantees, save warnings, payment vs rate limit semantics, and /v1 API rate limits."
canonical: "https://grid82.com/docs/developers/rest/errors"
updated: "2026-11-20"
---

# Errors and 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

| Code                | HTTP  | Meaning                                                                              |
| ------------------- | ----- | ------------------------------------------------------------------------------------ |
| `unauthenticated`   | `401` | Missing/invalid bearer token, or token issued for the wrong plane                    |
| `forbidden`         | `403` | Role permissions or credential scopes reject this action                             |
| `not_found`         | `404` | Resource missing, deleted, or outside your visible record scope                      |
| `conflict`          | `409` | Concurrent modification (`baseVersion`/`baseRevision`) or reused `Idempotency-Key`   |
| `validation_failed` | `422` | Malformed input, unknown key, invalid cursor, or invalid field type value            |
| `payment_required`  | `402` | Plan quota, workflow step cap, or AI credit balance reached (waiting won't clear it) |
| `rate_limited`      | `429` | Request rate ceiling reached (back off and retry)                                    |
| `not_implemented`   | `501` | Capability unavailable on this deployment                                            |
| `internal`          | `500` | Unexpected 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.
