Errors

Error response

REST errors include a code, a message, and a request ID. A parameter may identify the input to check. For example, a lookup-table query can return:

{
  "error": {
    "code": "invalid_filter",
    "message": "This table can't be filtered yet. Try again shortly.",
    "param": "filter"
  },
  "request_id": "7d0c3b5e-2f4a-4b8c-9d1e-6a5f3c2b1e0d"
}

Use error.code in your application and read error.message and error.param to decide what to correct. When contacting support, quote request_id, which matches the X-Request-Id header. Do not send credentials or customer data.

You can supply a UUID in X-Request-Id; other values are replaced. Handle an unfamiliar error code according to its HTTP status. The tables below are not an exhaustive list: each resource reference describes its own responses.

Authentication and access

HTTP status	Code	What to do
400	credential_in_url	Remove the credential from the URL, rotate the exposed key, and use the authorization header.
401	missing_credential, invalid_credential, credential_expired, or credential_revoked	Check the credential and use a current key or reconnect the AI app.
402	payment_overdue	An admin resolves payment in Billing.
403	plan_required	An admin checks whether the plan includes the requested feature.
403	not_available	Check the organization's access to the API family, including its alpha invitation.
403	insufficient_scope	Check the operation's required permissions and selected resources.
404	resource_not_found	Check the path, IDs, permissions, and ownership. An unavailable resource may be indistinguishable from one that does not exist.
423	organization_reopening	Retry after the organization finishes reopening.
428	customer_agreement_required	An admin finishes business setup in Neon Deer.

A connection can read a resource without controlling it. Reading a scheduled batch or webhook endpoint does not automatically allow changing, canceling, or transferring it. Personal notification-preference routes need a person-backed AI connection; a standalone API key has no such person.

Invalid input and conflicts

HTTP status	Example code	What to do
400	invalid_request	Correct the indicated parameters or body using that operation's schema.
400	invalid_filter or invalid_value	Check the filter format, supported operators, and value types for the resource. Filter formats differ between API families.
400	invalid_cursor	Continue with the original read settings or restart using that endpoint's pagination rules.
409	version_conflict	Read the resource again, review what changed, and retry only if the change is still appropriate.
409	idempotency_conflict	Inspect the current outcome. Do not reuse a request key for a different request.
413	request_too_large	Send a smaller selection or body.
429	rate_limited	Follow Retry-After and back off.
503	service_unavailable	Follow retry guidance and report a persistent failure.

A changed workflow requires a new read before scheduling. A changed merge plan, recovery plan, settings resource, or ownership record can require fresh versions and a new decision. Do not copy a newer version into a retry without reviewing what changed.

Lookup-table failures

HTTP status	Code	What to do
403	operation_not_allowed	Check whether this table accepts the write and whether the key has the required field access. Row deletion requires All fields.
403	field_not_writable	Write to your own fields rather than source-managed fields.
403	plan_capacity_exceeded	Remove unneeded rows or review the plan.
409	lookup_key_required	Choose a writable field configured as a lookup key.
409	key_conflict	Correct a repeated unique value or update the existing row.
409	table_busy	Wait for the current table change before retrying.
409	table_capacity_exceeded	Remove unneeded rows or contact support.
409	table_filling or table_fill_failed	Wait for the rows to finish loading, or open the table in Neon Deer and retry the failed fill.
422	batch_rejected	Read each add-or-update result, correct the failed items, and send a new request. Nothing was written by that all-or-nothing request.

An empty lookup query returns 200 and data: []. An unreadable table returns 404; unreadable fields are omitted and cannot be selected or filtered. Authentication, setup, and body-size checks can happen before table access is checked.

Accepted work and uncertain outcomes

An accepted operation is not necessarily finished, and a completed batch can contain failed items. Inspect operation status and each item's result. An uncertain response does not prove that no changes completed.

Correct invalid input, access, and credential problems before retrying. For temporary failures and safe write retries, follow rate limits and writes, versions, and retries. MCP transport errors and tool results are covered in the MCP protocol guide.