Errors

All errors return a non-2xx HTTP status and a plain-text response body containing the error message. The HTTP status line also includes the error message for convenience.

Status codes

Status Meaning
401 Missing, malformed, or invalid Bearer token; revoked key; IP not in whitelist
403 API key is read-only and called a write method; endpoint not exposed to API keys; key has no access to the requested workspace
402 Plan limit exceeded (workspace count, web form count, automation runtime)
405 Wrong HTTP method — a state-changing endpoint was called with GET
413 Request body too large (file uploads are capped at 50 MB decoded)
429 Rate limit exceeded (either hourly or per-minute bucket)
500 Validation error, a table validation rule blocking the write, an application-level exception, or unexpected failure
503 API access has been disabled on this account

Example

HTTP/1.1 401 Invalid API key
Content-Type: text/plain; charset=UTF-8

Invalid API key

500 covers most client errors

Be aware that 500 is not only used for server faults. Almost every client-side problem — a missing parameter, an unknown table or record id, an invalid field value, a conflict such as Already subscribed — also returns 500 with a descriptive message in the body. There is currently no machine-readable error code, so distinguishing these means matching on the message text.

Messages you may see on a 500 include Invalid Table, Record not found, Invalid parameters, Invalid filter, Invalid field for where: <name>, Invalid compare for where: <op>, Invalid Option <x> for <Field>, Unassignable - cannot set computed field: <name>, Unauthorized - no field edit permissions for field: <name>, Missing title, Already subscribed, and Not subscribed.

Database-level failures are reported generically (Database error) — the underlying driver message is never returned.

Content types

  • Errors are text/plain; charset=UTF-8, with the message repeated in the status line.
  • Successful responses are application/json; charset=UTF-8.

Note that HTTP/2 drops the status reason-phrase, so read the body for the message rather than relying on the status line.

Recommendations

  • Check the HTTP status code first.
  • For 401s, verify the Authorization header is present, well-formed (Bearer <token>), and that the token has not been rotated or deleted.
  • For 403s on workspaces, verify the key's workspace whitelist includes the workspace you're requesting.
  • For 405s, use POST. Only read endpoints (get, list, query, count, ids, execute, and similar) accept GET.
  • For 402s, upgrade the account plan or reduce usage before retrying.
  • For 429s, respect Retry-After and back off.
  • For 500s, the body contains the exception message. Common causes: missing required fields, invalid field types, referencing an unknown table ID, or a table validation rule rejecting the write — the body carries the rule's message. Note a rule sees API writes as origin api, so a table may be configured to allow your integration while blocking interactive edits.