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:
{
"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). /v1REST 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 return429 rate_limitedwith aRateLimit-Policyresponse header.