Errors catalogue

Codes are extracted from API, OAuth, watch, ask and stdio MCP emission sites. Parcel errors use error.code; watch uses an error string; OAuth uses its own JSON error; ask may send error SSE data. HTTP status, error code and coverage are separate signals. Internal watch admission codes can be suppressed as unsafe_event, rather than returned to the caller.

-32600

Invalid or oversized JSON-RPC request.

What to do: Send a supported JSON-RPC request shape and a valid id within transport bounds.

Emission sites: landfeed/mcp/server.mjs:120, landfeed/mcp/server.mjs:40.

-32601

The JSON-RPC method does not exist.

What to do: Use initialize, tools/list, tools/call or another supported protocol method.

Emission sites: landfeed/mcp/server.mjs:79.

-32602

JSON-RPC parameters or the requested tool are invalid.

What to do: Match the method schema and use a tool returned by tools/list.

Emission sites: landfeed/mcp/server.mjs:55, landfeed/mcp/server.mjs:71.

-32603

Internal JSON-RPC server failure.

What to do: Retain the call context, check billing if a tool started, and retry a read later.

Emission sites: landfeed/mcp/server.mjs:86, landfeed/mcp/server.mjs:88.

-32700

JSON-RPC parse failure.

What to do: Send valid UTF-8 JSON, one stdio message per line.

Emission sites: landfeed/mcp/server.mjs:98.

access_denied

Authorization was refused or its redirect policy changed.

What to do: Start consent again with a registered redirect; ask the operator if it is no longer allowed.

Emission sites: landfeed/api/landfeed_api/oauth.py:95, mcp==1.30.0/server/auth/provider.py:64.

account_inactive

The account is disabled.

What to do: Use an active account or ask account support.

Emission sites: landfeed/api/landfeed_api/watch/store.py:35.

account_required

A static benchmark credential cannot identify an account.

What to do: Use an issued account API key.

Emission sites: landfeed/api/landfeed_api/routers/watch.py:39.

ambiguous

Several parcel or area candidates match; HTTP 200. Candidate discovery is charged.

What to do: Ask the user for obręb or choose an explicitly confirmed candidate id; never pick silently.

Emission sites: landfeed/contracts/envelope.json:1.

billing_unavailable

Ask could not settle its reserved work. New artifacts and factual text are withheld.

What to do: Retain meta.request_id, inspect the account and reconcile settlement before replaying work.

Emission sites: landfeed/api/landfeed_api/ask/router.py:228.

blocked_destination

The webhook destination resolves to an unsafe address.

What to do: Use public HTTPS on port 443; correct DNS before reconfiguring the webhook.

Emission sites: landfeed/api/landfeed_api/watch/network.py:100.

body_too_large

The request body exceeds the endpoint cap.

What to do: Reduce the body; watch accepts at most 256 KiB.

Emission sites: landfeed/api/landfeed_api/routers/watch.py:86.

cancelled

The stdio MCP client cancelled the call; billing is unknown.

What to do: Check account usage before repeating a paid operation.

Emission sites: landfeed/mcp/bridge.mjs:127.

client_result_required

The continuation expects a client tool result.

What to do: Resend the signed continuation with matching client_results.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:50.

confirmation_required

The continuation expects explicit action confirmation.

What to do: Ask the user and resend confirmation for the signed step_id.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:55.

conflicting_historical_evidence

Historical event evidence contradicts the saved change.

What to do: Do not treat a suppressed event as no change; operator must repair producer evidence.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:122, landfeed/api/landfeed_api/watch/matching.py:207, landfeed/api/landfeed_api/watch/matching.py:209.

conflicting_version_provenance

Event version provenance contradicts its evidence.

What to do: Operator must reconcile version/source evidence; do not reconstruct it from current data.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:183.

context_too_large

Conversation evidence exceeds bounded context limits.

What to do: Resend only relevant signed results; at most 40 results and 512,000 bytes total.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:27, landfeed/api/landfeed_api/ask/conversation.py:66.

duplicate_artifact

An artifact identifier occurs more than once.

What to do: Send each complete signed artifact once.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:32.

event_type_has_no_producer

The requested event family has no serving producer.

What to do: Use one of the seven supported layer.changed watch filters.

Emission sites: landfeed/api/landfeed_api/watch/validation.py:60.

expired_continuation

The signed conversation continuation expired.

What to do: Start a new turn with fresh context; continuations last one hour.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:25.

idempotency_conflict

A request key was reused with different watch items.

What to do: Use the original items for a retry, or a new key for a new action.

Emission sites: landfeed/api/landfeed_api/watch/store.py:89.

incomplete_version_provenance

An event lacks the version/source evidence required for delivery.

What to do: Operator must repair the producer; never infer a negative from a missing delivery.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:51.

insufficient_credits

Ask could not reserve the declared budget.

What to do: Reduce max_credits within the supported range or fund the account before asking again.

Emission sites: landfeed/api/landfeed_api/ask/router.py:228.

internal

The server failed to complete the operation; HTTP 500, refunded.

What to do: Retain meta.request_id and retry a read later; check billing after an interrupted response.

Emission sites: landfeed/api/landfeed_api/app.py:469, landfeed/contracts/envelope.json:1.

invalid_arguments

The stdio tool received an invalid argument object or path value.

What to do: Match the tool inputSchema; path arguments must be nonempty strings.

Emission sites: landfeed/mcp/bridge.mjs:71, landfeed/mcp/bridge.mjs:76, landfeed/mcp/bridge.mjs:81.

invalid_client

OAuth client authentication failed.

What to do: Check client registration and auth method, then reconnect.

Emission sites: landfeed/api/landfeed_api/oauth.py:365, mcp==1.30.0/server/auth/provider.py:81.

invalid_client_metadata

OAuth registration requested unsupported metadata.

What to do: Use authorization_code/refresh_token and a supported client authentication method.

Emission sites: landfeed/api/landfeed_api/oauth.py:83, landfeed/api/landfeed_api/oauth.py:85, mcp==1.30.0/server/auth/provider.py:50.

invalid_client_tool

A declared client tool schema or its conversation input is invalid.

What to do: Send a self-contained local JSON schema and correctly shaped client results; remote/dynamic references are rejected.

Emission sites: landfeed/api/landfeed_api/ask/router.py:167.

invalid_digest

Signed evidence or its account binding failed verification.

What to do: Send the original signed object unchanged from this account; otherwise start again.

Emission sites: landfeed/api/landfeed_api/ask/signing.py:41.

invalid_grant

OAuth code or refresh token is expired, consumed or invalid.

What to do: Restart authorization; do not replay an old rotated refresh token.

Emission sites: landfeed/api/landfeed_api/oauth.py:165, landfeed/api/landfeed_api/oauth.py:194, landfeed/api/landfeed_api/oauth.py:298, mcp==1.30.0/server/auth/provider.py:81.

invalid_id

A watch/resource UUID is malformed.

What to do: Copy the UUID returned by creation/listing.

Emission sites: landfeed/api/landfeed_api/routers/watch.py:48.

invalid_input

Request parameters or JSON do not match the operation; generally HTTP 400 and free.

What to do: Correct required fields, types and exclusivity; inspect error.hint where present.

Emission sites: landfeed/api/landfeed_api/account/router.py:51, landfeed/api/landfeed_api/account/router.py:57, landfeed/api/landfeed_api/app.py:460, landfeed/api/landfeed_api/app.py:549, landfeed/api/landfeed_api/app.py:557, landfeed/api/landfeed_api/app.py:577, landfeed/api/landfeed_api/mcp_remote.py:39, landfeed/api/landfeed_api/routers/billing.py:141, landfeed/api/landfeed_api/routers/billing.py:87, landfeed/api/landfeed_api/routers/billing.py:93, landfeed/api/landfeed_api/routers/watch.py:104, landfeed/api/landfeed_api/routers/watch.py:116, landfeed/api/landfeed_api/routers/watch.py:183, landfeed/api/landfeed_api/routers/watch.py:188, landfeed/api/landfeed_api/routers/watch.py:91, landfeed/api/landfeed_api/routers/watch.py:99, landfeed/api/landfeed_api/watch/store.py:81, landfeed/api/landfeed_api/watch/validation.py:48, landfeed/contracts/envelope.json:1.

invalid_polygon

The supplied geometry cannot be admitted.

What to do: Use a valid WGS84 Polygon/MultiPolygon within endpoint limits.

Emission sites: landfeed/api/landfeed_api/watch/store.py:65, landfeed/api/landfeed_api/watch/validation.py:96.

invalid_redirect_uri

OAuth callback URI is not allowed by server policy.

What to do: Register an exact client callback allowed by the operator.

Emission sites: landfeed/api/landfeed_api/oauth.py:81, mcp==1.30.0/server/auth/provider.py:50.

invalid_request

The OAuth request is incomplete or violates resource/PKCE requirements.

What to do: Use S256 PKCE, exact redirect_uri and the discovered MCP resource.

Emission sites: landfeed/api/landfeed_api/oauth.py:290, landfeed/api/landfeed_api/oauth.py:307, landfeed/api/landfeed_api/oauth.py:367, landfeed/api/landfeed_api/oauth.py:93, landfeed/api/landfeed_api/oauth.py:97, mcp==1.30.0/server/auth/provider.py:64, mcp==1.30.0/server/auth/provider.py:81.

invalid_response

The stdio bridge received invalid JSON, UTF-8 or a non-envelope response. Billing is unknown.

What to do: Keep the request context, check usage and report the transport failure.

Emission sites: landfeed/mcp/bridge.mjs:119, landfeed/mcp/bridge.mjs:130.

invalid_scope

OAuth requested a scope other than landfeed:read.

What to do: Request landfeed:read.

Emission sites: landfeed/api/landfeed_api/oauth.py:100, mcp==1.30.0/server/auth/provider.py:64, mcp==1.30.0/server/auth/provider.py:81.

invalid_software_statement

OAuth registration contains an invalid software statement.

What to do: Remove unsupported software metadata or use dynamic client registration with valid client metadata.

Emission sites: mcp==1.30.0/server/auth/provider.py:50.

invalid_target

The OAuth resource does not identify this MCP server.

What to do: Use the resource in protected-resource discovery, ending /mcp.

Emission sites: landfeed/api/landfeed_api/oauth.py:296.

invalid_webhook_url

Webhook URL syntax, protocol or privacy admission failed.

What to do: Use a public HTTPS URL on port 443 with no credentials, fragment or private fields.

Emission sites: landfeed/api/landfeed_api/watch/network.py:63.

missing_artifact

Conversation history refers to an artifact absent from results.

What to do: Resend the full original signed artifact, including data.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:36.

missing_historical_evidence

Historical event evidence or its dated source is missing.

What to do: Operator must repair source evidence; current dates cannot replace historical dates.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:201, landfeed/api/landfeed_api/watch/matching.py:42, landfeed/api/landfeed_api/watch/matching.py:78, landfeed/api/landfeed_api/watch/matching.py:84, landfeed/api/landfeed_api/watch/matching.py:87, landfeed/api/landfeed_api/watch/matching.py:99.

not_covered

The input resolved outside the loaded data; this is unknown, not a negative result.

What to do: Inspect scope/source/note; use another source. The uncovered work is refunded.

Emission sites: landfeed/api/landfeed_api/app.py:199, landfeed/api/landfeed_api/app.py:212, landfeed/api/landfeed_api/app.py:216, landfeed/api/landfeed_api/app.py:228, landfeed/api/landfeed_api/app.py:231, landfeed/api/landfeed_api/app.py:344, landfeed/api/landfeed_api/app.py:392, landfeed/api/landfeed_api/app.py:432, landfeed/contracts/envelope.json:1.

not_found

No matching resource was found; parcel reads refund the work.

What to do: Check the id and account ownership; refine q or point where applicable.

Emission sites: landfeed/api/landfeed_api/account/router.py:49, landfeed/api/landfeed_api/app.py:193, landfeed/api/landfeed_api/app.py:208, landfeed/api/landfeed_api/app.py:577, landfeed/api/landfeed_api/watch/store.py:114, landfeed/api/landfeed_api/watch/store.py:120, landfeed/api/landfeed_api/watch/store.py:74, landfeed/api/landfeed_api/watch/store.py:91, landfeed/contracts/envelope.json:1.

note_required

A correction event lacks its explanatory note.

What to do: Operator must supply the producer correction note before delivery.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:148.

private_content

Watch input contains forbidden owner or land-register content.

What to do: Remove private fields; use only cadastral parcel/area selectors.

Emission sites: landfeed/api/landfeed_api/watch/validation.py:50.

provider_unavailable

The ask provider failed.

What to do: Retry later after checking settled billing; factual output is withheld on failed settlement.

Emission sites: landfeed/api/landfeed_api/ask/providers/codex_pool.py:205, landfeed/api/landfeed_api/ask/v2.py:155.

rate_limited

A rate, concurrency, credit or team quota limit refused admission; HTTP 429.

What to do: Inspect balance, plan/quota and any Retry-After; reduce concurrency and retry reads with backoff.

Emission sites: landfeed/api/landfeed_api/account/router.py:53, landfeed/api/landfeed_api/ask/router.py:197, landfeed/api/landfeed_api/billing/metering.py:110, landfeed/api/landfeed_api/mcp_remote.py:114, landfeed/api/landfeed_api/routers/billing.py:126, landfeed/api/landfeed_api/routers/billing.py:89, landfeed/api/landfeed_api/watch/store.py:130, landfeed/contracts/envelope.json:1.

resolution_unavailable

Webhook destination DNS could not be resolved.

What to do: Retry later; fix DNS if persistent.

Emission sites: landfeed/api/landfeed_api/watch/network.py:92, landfeed/api/landfeed_api/watch/network.py:98.

response_too_large

The stdio response exceeded 16 MiB; billing is unknown.

What to do: Reduce requested data and check usage before replay.

Emission sites: landfeed/mcp/bridge.mjs:103.

server_error

OAuth could not complete due to a server failure.

What to do: Reconnect later; report the failure without sending secrets.

Emission sites: landfeed/api/landfeed_api/oauth.py:369, mcp==1.30.0/server/auth/provider.py:64.

signing_unavailable

Ask conversation signing is unavailable.

What to do: Retry later; operator must configure the persistent signing secret.

Emission sites: landfeed/api/landfeed_api/ask/signing.py:30.

source_unavailable

A required source or accounting/authentication service failed; HTTP 503.

What to do: Retry the read later; retain request_id and inspect billing. Do not interpret this as no data.

Emission sites: landfeed/api/landfeed_api/account/router.py:61, landfeed/api/landfeed_api/app.py:462, landfeed/api/landfeed_api/app.py:464, landfeed/api/landfeed_api/app.py:466, landfeed/api/landfeed_api/auth.py:45, landfeed/api/landfeed_api/billing/metering.py:110, landfeed/contracts/envelope.json:1.

temporarily_unavailable

OAuth endpoint exceeded its per-process request budget.

What to do: Respect Retry-After (60 seconds) and restart authorization if necessary.

Emission sites: landfeed/api/landfeed_api/oauth.py:358, mcp==1.30.0/server/auth/provider.py:64.

timeout

The stdio bridge exceeded its 30-second deadline; billing is unknown.

What to do: Check usage before retrying; the server may have completed the work.

Emission sites: landfeed/mcp/bridge.mjs:128.

transport_error

The stdio bridge could not complete HTTP; billing is unknown.

What to do: Check service connectivity and account usage before replay.

Emission sites: landfeed/mcp/bridge.mjs:139.

unapproved_software_statement

The OAuth server does not approve the submitted software statement.

What to do: Use supported dynamic registration and contact the operator for an approved client policy.

Emission sites: mcp==1.30.0/server/auth/provider.py:50.

unapproved_source

Event evidence references a source without the required serving approval.

What to do: Operator must review the source; never substitute an unapproved answer.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:28.

unauthorized

Credentials are missing, invalid or lack account/role authority (401 or 403).

What to do: Use a valid account key, reconnect OAuth, or request the required team role.

Emission sites: landfeed/api/landfeed_api/account/router.py:28, landfeed/api/landfeed_api/account/router.py:47, landfeed/api/landfeed_api/auth.py:38, landfeed/api/landfeed_api/routers/billing.py:85, landfeed/api/landfeed_api/routers/watch.py:36, landfeed/contracts/envelope.json:1.

unauthorized_client

The OAuth client is not allowed to use this grant.

What to do: Register a client supporting authorization_code and refresh_token, then reconnect.

Emission sites: mcp==1.30.0/server/auth/provider.py:64, mcp==1.30.0/server/auth/provider.py:81.

unavailable

Ask cannot finish due to provider, signing or settlement availability.

What to do: Keep request_id; inspect billing and retry only when safe.

Emission sites: landfeed/api/landfeed_api/ask/streaming.py:48, landfeed/api/landfeed_api/ask/v2.py:151.

unexpected_continuation

A confirmation/client result does not match the continuation kind.

What to do: Resend only the matching signed action/result or start a new turn.

Emission sites: landfeed/api/landfeed_api/ask/conversation.py:58.

unknown_tool

The stdio MCP tool name is not in the six-tool catalogue.

What to do: Call tools/list and use a published tool name.

Emission sites: landfeed/mcp/bridge.mjs:69.

unsafe_event

Notification evidence failed schema, source or privacy admission.

What to do: Operator must correct the producer; a suppressed notification proves no absence.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:141, landfeed/api/landfeed_api/watch/matching.py:151, landfeed/api/landfeed_api/watch/matching.py:160, landfeed/api/landfeed_api/watch/matching.py:167, landfeed/api/landfeed_api/watch/matching.py:172, landfeed/api/landfeed_api/watch/matching.py:177, landfeed/api/landfeed_api/watch/matching.py:185, landfeed/api/landfeed_api/watch/matching.py:214, landfeed/api/landfeed_api/watch/matching.py:226, landfeed/api/landfeed_api/watch/worker.py:67.

unsupported_grant_type

The OAuth grant type is unsupported.

What to do: Use authorization_code or refresh_token; client_credentials is not supported.

Emission sites: mcp==1.30.0/server/auth/provider.py:81.

unsupported_legacy_event

A stored legacy event has no safe supported notification shape.

What to do: Use supported layer.changed events; operator must implement a typed producer for other families.

Emission sites: landfeed/api/landfeed_api/watch/matching.py:114.

unsupported_response_type

OAuth authorization requested a response type other than code.

What to do: Request response_type=code with PKCE S256.

Emission sites: mcp==1.30.0/server/auth/provider.py:64.

validation_work_limit

Watch validation exceeds item/vertex work bounds (413).

What to do: Limit to 100 items and 1024 polygon vertices in aggregate; reduce the request.

Emission sites: landfeed/api/landfeed_api/watch/validation.py:67, landfeed/api/landfeed_api/watch/validation.py:79, landfeed/api/landfeed_api/watch/validation.py:91.

watch_limit

The shared plan watch-item quota is exhausted (409).

What to do: Remove items or obtain an approved larger limit; zero can mean operator configuration is pending.

Emission sites: landfeed/api/landfeed_api/watch/store.py:46, landfeed/api/landfeed_api/watch/store.py:58.

watch_unavailable

Watch storage or processing is unavailable (503).

What to do: Retry reads later; use the creation idempotency key when retrying creation.

Emission sites: landfeed/api/landfeed_api/ask/router.py:204.

webhook_unconfigured

The watch has no configured webhook to rotate.

What to do: Configure the webhook first, then save its one-time secret securely.

Emission sites: landfeed/api/landfeed_api/watch/store.py:157.