Errors

Seamward returns stable, machine-matchable error identifiers. This page lists what each one means and what to do about it, grouped by where you meet it.

Unexpected request failures

503 {"error":"mode_cutover_write_paused"} with Retry-After: 1 means authenticated writes are temporarily paused for maintenance. Wait at least that many seconds and retry the same request and idempotency key with bounded backoff. Keep observation event IDs unchanged and generate a fresh ingest signature. After an unknown outcome, recover the original operation status before reviewing another change. See temporary write maintenance.

Connection checks

GET /v1/collector/connection returns 401 unauthenticated when credentials or request signing fail, and 429 connection_rate_limited when its per-client limit is reached. Check the credential pair, revocation and system clock for 401; wait for Retry-After seconds for 429. See the connection API.

The local CLI also returns safe connection_* references for missing or conflicting configuration, unsafe endpoints, unavailable services, invalid responses and scope mismatches. Follow the connection-check recovery table. Network or response failures do not mean that credentials are invalid, and a successful connection check does not verify application startup or traffic.

The local setup MCP can return setup_metadata_unsafe when its metadata path or ignore rules need review. It does not overwrite existing rules. Ensure .seamward/.gitignore includes private/, runtime-validation.json, **/setup-state.json and **/*.lock without negation rules, and check that the metadata paths are regular, owner-controlled files, then review setup again. Already tracked state still needs to be excluded from commits separately.

Unexpected internal failures return 500 {"error":"service_unavailable"} without exposing database arguments or credentials. Retry with bounded backoff and contact the operator if the failure persists. Rejected malformed transport requests return invalid_request with their 4xx status; oversized bodies return 413 {"error":"request_too_large"}. Documented domain errors keep their specific identifiers.

Ingestion and signing

From POST /ingest, the endpoint your backend talks to:

A 207 response is not an error: the batch was mixed, and each rejected item carries its own issues array. The API reference lists the per-item rejection strings.

Workload limits

Ingestion allows 600 requests and 6,000 attempted observations per integration per minute, with a shared ceiling of 30,000 observations per workspace per minute. Empty batches still consume a request. Rotating a credential does not reset its integration budget. All API instances share these fixed minute windows. Monthly usage displayed in the console remains informational.

Repair requests allow five submissions per user per workspace per minute and 20 per workspace per minute. A workspace can have at most ten proposals queued, generating or validating, and only one active proposal per incident. A full workspace returns 429 repair_capacity_exceeded with Retry-After: 60; wait for pending work to finish. A duplicate incident request returns 409 repair_proposal_in_progress with the existing proposalId. Rejected admissions create no proposal, replay dataset or queued job.

Collectors keep transient failures in their bounded local queues. Sustained traffic above these limits can exhaust that queue and increment dropped counts; monitor collector diagnostics and reduce observed traffic or batch submission frequency before retrying.

Contract API

From the workspace-scoped Contract API:

Console and workflow

Console-facing routes return snake_case identifiers. The ones worth recognizing:

Legacy internal routes are not part of the supported public API. Public and workspace-scoped contract routes use the snake_case identifiers documented above.

Integration deletion

Assisted setup MCP

The local @seamward/setup-mcp server returns an error object containing code, message, retryable, and recovery. Retry the same request only when retryable is true. State, review, configuration, and permission errors need the listed recovery step first.

For runtime_credentials_unavailable, run review_setup selecting the existing Integration, review credentialAction: rotate, and separately approve apply_setup only if replacement is intended. Then rerun seamward setup credentials. Do not recreate the Integration or paste tokens into chat.

Interrupted worker execution

Retired custom replay

410 custom_replay_retired means the legacy endpoint for uploading custom adapter source has been retired. Do not retry it. Request a supported repair proposal from the incident's Repair tab. Existing run evidence remains readable by authorized members.

Collector-side signals

The collector never throws into your application after construction, so its failures surface as counters from stats():

| skippedInspections rising | Inspection was skipped because of size, time, content type or capacity bounds | Check body types, sizes and burst volume; see resource limits | | pendingInspections | Current bounded inspection work, a live gauge | Check whether bursts approach maxPendingInspections |

| quotaRejected rising | Monthly quota rejection, also included in rejected | Inspect the account allowance and wait until the UTC reset. Discarded telemetry is not recovered. | | quotaResetAtSeconds greater than zero | Delivery is paused until this Unix timestamp | New traffic resumes after reset. Your application keeps running. |

See monthly mode allowances for the full 403 response and the distinction from 429 throttling.

Retry rules, in one list

• Retry: 5xx, 409 integration_not_available, 429, network failures. Idempotent by eventId, so redelivery is always safe.
• Fix first, then retry: 400, 401, per-item schema rejections.
• Never retry in a loop: 403, 404. A 403 observation_monthly_quota_exhausted means the mode allowance is exhausted until the reported UTC resetAt; other 403s require correcting permissions or scope.

Replay evidence capacity exceeded

replay_evidence_capacity_exceeded is a 409 response to replay dataset or repair proposal creation when the current incident requires more than 1,000 fixtures. limit and total explain the boundary. The full evidence page remains available, including search and pagination. No dataset or proposal is created by the rejected request. Reconciliation updates the active set as outcomes recover; rerun the request only after its complete evidence fits the limit. An explicitly selected dataset whose observation IDs no longer match the complete current evidence returns 409 replay_evidence_snapshot_changed. Create a fresh dataset or start proposal generation without selecting the stale dataset. Automatic preparation rebuilds an immutable dataset when the current evidence changes.

Sandbox work and burst limits

A monthly repair validation error returns { "error": "sandbox_repair_monthly_limit", "limit": 3, "resetsAt": "2026-10-01T00:00:00.000Z" }. The date is the next UTC month boundary. Reads, existing operation status and credential revocation remain available when allowances are exhausted. Review pooled usage and keys.