Error codes

Every error Ablo returns, by category. This page is generated from the canonical registry — its anchors are the target of each error's doc_url.

Error contract version: 2026-07-23 (also sent on the Ablo-Version response header).

Every error — over HTTP or WebSocket — carries the same envelope:

{
  "type": "AbloValidationError",
  "code": "invalid_body",
  "message": "The request body was missing, unparseable, or the wrong shape.",
  "doc_url": "https://docs.abloatai.com/errors#invalid_body",
  "request_id": "req_8f3a…"
}

type is the coarse class (catch with instanceof, or switch on it); code is the stable machine identifier documented below; request_id correlates to your server logs. Some errors carry extra structured fields (e.g. a schema push adds warnings).

Authentication

Missing, invalid, revoked, or expired credentials. Re-authenticate.

api_key_required

HTTP 401 · not retryable

This operation requires an API key, and none was presented. Send one as Authorization: Bearer <key>.

apikey_expired

HTTP 401 · not retryable

This ephemeral API key has expired. Mint a fresh key from your still-valid session and retry the request.

apikey_invalid

HTTP 401 · not retryable

This API key isn’t one Ablo recognizes — it may be mistyped, truncated, or belong to a different environment. Check the key and try again.

apikey_missing

HTTP 401 · not retryable

The request arrived without an API key. Send one as Authorization: Bearer <key>.

apikey_revoked

HTTP 401 · not retryable

This API key has been revoked and can no longer be used. Mint a new key from the dashboard.

auth_no_credentials

HTTP 401 · not retryable

No recognized authentication credential was presented — no API key and no bearer JWT. Send Authorization: Bearer <token>.

browser_apikey_blocked

client-only · not sent over the network

A raw API key was used from a browser, where anyone can read it. Keep secret keys server-side and hand the browser a short-lived ephemeral key instead.

capability_id_missing

HTTP 401 · not retryable

This request must name a capability id, but none was provided.

capability_required

HTTP 401 · not retryable

This operation requires a capability, and none was presented.

exchange_failed

HTTP 401 · not retryable

The API key could not be exchanged for a working credential — the exchange was rejected. Check that the key is still valid.

file_upload_auth_required

HTTP 401 · not retryable

File uploads require an authenticated session. Sign in and retry.

identity_missing_organization

HTTP 401 · not retryable

Authentication succeeded, but the credential resolves to no organization, so requests cannot be scoped. Check that the key or token carries an organization.

identity_resolve_failed

HTTP 401 · not retryable

The server could not resolve an identity for this credential — the identity lookup was rejected. Check that the credential is still valid.

jwt_audience_mismatch

HTTP 401 · not retryable

The bearer JWT’s aud (audience) claim does not match the audience this issuer is registered with.

jwt_expired

HTTP 401 · not retryable

The bearer JWT has expired. Obtain a fresh token from your identity provider and retry.

jwt_invalid

HTTP 401 · not retryable

The bearer JWT failed validation for a reason the server could not classify further. Check the token’s issuer, signature, audience, and expiry.

jwt_issuer_untrusted

HTTP 401 · not retryable

The bearer JWT’s iss is not a registered trusted issuer. Check the token’s issuer claim, or register the issuer with your deployment before retrying.

jwt_malformed

HTTP 401 · not retryable

The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent.

jwt_missing_issuer

HTTP 401 · not retryable

The bearer JWT has no iss (issuer) claim, so it cannot be routed to a trusted issuer.

jwt_missing_organization

HTTP 401 · not retryable

The bearer JWT carries no organization context — neither a fixed org for the issuer nor the configured organization claim.

jwt_missing_subject

HTTP 401 · not retryable

The bearer JWT has no sub (subject) claim to identify the user.

jwt_org_membership_denied

HTTP 403 · not retryable

The bearer JWT’s subject is not an active member of the organization in its org_id claim (removed, suspended, or the claim does not match a membership).

jwt_signature_invalid

HTTP 401 · not retryable

The bearer JWT’s signature could not be verified against the issuer’s JWKS (wrong key, rotated key, or forged token).

session_expired

HTTP 401 · not retryable

Your session has expired or is no longer valid. Sign in again to continue.

source_api_key_unresolved

HTTP 401 · not retryable

The API key presented for this data source could not be resolved to a known key. Check the key and its environment.

Permission

Credentials were valid but the action is forbidden for this caller.

byo_host_not_allowed

HTTP 403 · not retryable

The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used.

byo_role_cannot_enforce_rls

HTTP 403 · not retryable

The direct Postgres connector role cannot enforce row-level security.

byo_role_unreadable

HTTP 403 · not retryable

The direct Postgres connector role could not be introspected.

byo_tenant_tables_unforced_rls

HTTP 403 · not retryable

Tenant tables do not have RLS forced under the direct Postgres connector role.

database_host_not_allowed

HTTP 403 · not retryable

The database host resolves to a private, loopback, or link-local address, which Ablo’s servers will not connect to. Use a publicly resolvable host.

database_role_cannot_enforce_rls

HTTP 403 · not retryable

The database role Ablo connects with is a superuser or has BYPASSRLS, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS.

database_role_unreadable

HTTP 403 · not retryable

Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.

database_tables_unforced_rls

HTTP 403 · not retryable

Some synced tables do not have FORCE ROW LEVEL SECURITY applied, so the table owner can bypass row isolation. Run ALTER TABLE ... FORCE ROW LEVEL SECURITY on each synced table.

forbidden

HTTP 403 · not retryable

The caller lacks permission for this operation.

issuer_register_forbidden

HTTP 403 · not retryable

Registering a trusted issuer requires a secret (sk_) API key. The key presented is not a secret key.

organization_mismatch

HTTP 403 · not retryable

The request targeted an organization the caller is not scoped to.

permission_denied

HTTP 403 · not retryable

The participant is not allowed to execute this mutator.

project_scope_denied

HTTP 403 · not retryable

The request targeted a project the caller’s key is not scoped to.

schema_provisioning_forbidden

HTTP 403 · not retryable

Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.

test_database_not_registered

HTTP 403 · not retryable

Test mode requires a registered dev database for this org — run npx ablo init to register one for your test key.

wide_scope_forbidden

HTTP 403 · not retryable

This caller may not use a wide scope. Request a scope narrowed to the resources you need.

Capability

The connection’s resolved scope does not cover the attempted action.

capability_invalid

HTTP 403 · not retryable

This capability cannot be used — it is unknown, revoked, or expired. Request a fresh grant.

capability_scope_denied

HTTP 403 · not retryable

This action falls outside the scope granted to the connection, so it was denied.

Claim contention

The target is held by another participant, or a claim lease could not be acquired. Usually retryable once the holder releases.

claim_conflict

HTTP 409 · not retryable

Another participant holds a claim on this row, so the write was rejected. Take a claim with ablo.<model>.claim to queue fairly behind the holder, or re-read and rebase.

claim_lease_unavailable

HTTP 503 · retryable

The claim-lease coordination subsystem is temporarily unavailable, so the claim could not be processed. Retry shortly.

claim_lost

HTTP 409 · not retryable

The claim held on this row was lost before the write could apply. Re-acquire with ablo.<model>.claim and retry from its fresh snapshot.

claim_not_wired

client-only · not sent over the network

Claims were used, but this runtime has no claim support wired in. The standard Ablo({ schema, apiKey }) client wires it up automatically.

claim_queued

HTTP 409 · retryable

The claim was queued behind the current lease holder and will be granted in turn. Poll claims.retrieve({ claimId }) for the grant — the id rides on the error — or read claim.queue to see the line.

claim_wait_aborted

HTTP 409 · retryable

The wait for this claim lease was aborted before the lease was granted.

entity_claimed

HTTP 409 · not retryable

This row is currently claimed by another participant, so the write was blocked. Queue behind the holder with ablo.<model>.claim, or wait for the claim to clear.

fence_token_stale

HTTP 409 · not retryable

This write carried a fencing token below the row’s current high-water: a later holder claimed the row, wrote, and moved on while this claim was lapsed, so applying the write would silently overwrite their work. The claim is gone — re-claim the row and retry from the current state.

grant_timeout

HTTP 504 · retryable

The wait for the claim grant timed out before your turn arrived (waitTimeoutMs). Claim again to rejoin the line, raise the cap, or re-read and proceed without the claim.

model_claim_not_configured

client-only · not sent over the network

Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).

model_claimed

HTTP 409 · not retryable

Another participant holds a claim on this row. Read claim.state to see who holds it, or queue behind them with a claim of your own.

model_claimed_timeout

HTTP 409 · not retryable

Another participant held a claim on this row and did not release it in time. Retry, or read claim.state to see who holds it.

model_join_not_configured

client-only · not sent over the network

join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).

Conflict

The write collided with concurrent state (stale read, idempotency mismatch, incompatible change).

contention_exhausted

client-only · not sent over the network

A functional update kept losing to concurrent writes and exhausted its reconcile budget. Back off and retry, raise retries, or move the row to the WebSocket transport.

database_already_connected

HTTP 409 · not retryable

This database is already connected to another environment in your organization. Ablo streams a database from one environment at a time, so connecting it to a second one would leave the two reading the same change stream, and the newer connection would take the stream over from the older. Give this environment a database of its own — on a branching provider a branch of the same database is the usual answer, and it is what sandbox is for. If you meant to move the connection rather than add one, disconnect it from the environment that holds it with ablo connect deregister first.

foreign_key_violation

HTTP 409 · not retryable

The database rejected the write on a foreign-key constraint: a referenced row does not exist, or the row being deleted is still referenced by others. The error details name the constraint.

idempotency_conflict

HTTP 409 · not retryable

This Idempotency-Key was already used with a different request body. Reuse a key only to retry an identical request; otherwise generate a new one.

idempotency_key_expired

HTTP 409 · not retryable

This idempotency key belongs to an expired retained source intent and cannot be executed again safely. Use a new key only for a genuinely new write.

incompatible_change

HTTP 409 · not retryable

The schema change is incompatible with the schema currently deployed and cannot be applied as-is.

replication_reset_required

HTTP 409 · not retryable

A connected log plane has live rows for a mapped model that disappeared. Declare a rename or an explicit drop/reset before advancing the schema.

source_transport_pinned

HTTP 409 · not retryable

An earlier attempt under this idempotency key was pinned to a different source transport. Restore that route and retry the same key; Ablo will not switch a possibly committed write.

stale_context

HTTP 409 · not retryable

The row changed after you read it — the write’s readAt watermark is older than the current row version. Pass a function to update(id, current => next) and the SDK re-reads and retries for you; or re-read and retry by hand.

unique_violation

HTTP 409 · not retryable

The write duplicates a value that must be unique — another row already holds it. Choose a different value, or update the existing row.

update_aborted

client-only · not sent over the network

The functional update was aborted via its AbortSignal before the write landed; nothing was written.

Validation

The request payload or parameters were invalid. Fix the input and retry.

agent_perception_missing_context

HTTP 422 · not retryable

The agent perception request is missing context it needs to run. Include the required context fields and retry.

capability_id_required

HTTP 400 · not retryable

A capability id is required for this request.

check_violation

HTTP 400 · not retryable

The database rejected a value that fails one of its check constraints. The error details name the constraint; adjust the value and retry.

claim_id_required

HTTP 400 · not retryable

A claim id is required for this request.

cli_invalid_arguments

client-only · not sent over the network

The CLI was invoked with an unknown flag or a malformed flag value.

column_type_mismatch

HTTP 400 · not retryable

A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) — but a scalar column (integer, boolean, uuid, timestamp, …) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema.

commit_operation_action_required

HTTP 400 · not retryable

A commit operation is missing its action.

commit_operation_invalid

HTTP 400 · not retryable

A commit operation failed validation against the wire commit-operation schema — wrong field type (e.g. a string readAt), unknown type, or missing model. The whole batch was rejected; the error names the offending operation index and field path.

commit_operation_model_required

HTTP 400 · not retryable

A commit operation is missing its model.

commit_operation_required

HTTP 400 · not retryable

A commit must carry operation or operations.

commit_operation_unsupported

HTTP 400 · not retryable

A commit operation used an unsupported action.

commit_operations_ambiguous

HTTP 400 · not retryable

A commit supplied both operation and operations. Send one or the other, not both.

commit_too_many_operations

HTTP 400 · not retryable

A commit exceeded the per-commit operation limit; split it into smaller batches.

constraint_violation

HTTP 400 · not retryable

The database rejected the write on an integrity constraint. The error details identify the specific constraint.

database_not_replication_ready

HTTP 400 · not retryable

This database is not set up for logical replication yet. Every failing item — wal_level, the publication, the replication grant, a replica identity — is listed in the error details with its exact fix. ablo connect prints the one-time setup; ablo connect check verifies it.

database_unreachable

HTTP 400 · not retryable

Ablo could not reach this database to check that it can stream replication. The connection string may be wrong, the host may not be reachable from Ablo’s servers, or the credentials may not be accepted.

datasource_connection_unsupported

HTTP 400 · not retryable

This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead.

duration_invalid

client-only · not sent over the network

A duration value was not a number of seconds or a “500ms” | “30s” | “3m” | “24h” string.

events_required

HTTP 400 · not retryable

The request must include a non-empty events array.

idempotency_key_too_long

HTTP 400 · not retryable

The supplied Idempotency-Key exceeds the maximum length. Use a shorter key — a UUID works well.

ingest_failed

HTTP 400 · not retryable

The source-event batch was rejected during ingest and nothing was appended. Check the events against the expected shape and re-send.

invalid_body

HTTP 400 · not retryable

The request body was missing, unparseable, or the wrong shape.

invalid_id

HTTP 400 · not retryable

The id in the request is not a valid identifier.

invalid_input

HTTP 400 · not retryable

The mutator input could not be parsed or failed input validation.

invalid_json

HTTP 400 · not retryable

The request body was not valid JSON.

invalid_model

HTTP 400 · not retryable

The model name in the request is not a valid model identifier.

invalid_participant_kind

HTTP 400 · not retryable

The participant kind is not one the server recognizes.

invalid_request

HTTP 400 · not retryable

The request parameters were invalid.

invalid_schema

HTTP 400 · not retryable

The submitted schema could not be parsed.

invalid_sync_group

HTTP 400 · not retryable

Sync groups must be default or <namespace>:<id>.

malformed_claim

HTTP 400 · not retryable

The claim payload could not be parsed. A claim on a row must name the model and the entity it targets; a claim on a scope, which is what join opens, must name sync groups spelled kind:id or default. Check the payload shape and resend.

malformed_subscription

HTTP 400 · not retryable

The update_subscription payload was malformed; expected { syncGroups: string[] }.

mesh_message_from_id_spoof

HTTP 403 · not retryable

The mesh message’s from id does not match the authenticated sender, so it was rejected — participants may only send as themselves.

mesh_message_from_kind_mismatch

HTTP 403 · not retryable

The mesh message’s from kind does not match the kind of the authenticated sender, so it was rejected.

mesh_message_invalid_input

HTTP 400 · not retryable

The mesh message payload failed input validation and was not delivered.

model_identifier_missing

HTTP 400 · not retryable

The payload is missing the model’s identifier, so the target row cannot be determined. Include the id field.

model_query_failed

HTTP 400 · not retryable

The model query failed to execute. Check the query filters and operators.

model_required_field_missing

HTTP 400 · not retryable

The write is missing a field the model marks as required. Include the field and retry.

narrow_scope_required

HTTP 400 · not retryable

This request requires a scope narrowed to specific resources; the presented scope is too broad.

not_null_violation

HTTP 400 · not retryable

The database rejected the write because a required column was left empty — a not-null constraint. The error details name the column; supply a value and retry.

org_id_required

HTTP 400 · not retryable

An organization id is required for this request.

position_missing_parent

HTTP 400 · not retryable

This row gives a position but not the parent it belongs to, so the position cannot be resolved. Send the parent id alongside the position.

position_unknown_sibling

HTTP 400 · not retryable

This row is positioned relative to another row that is not in the same parent. Check that the neighbouring row id is correct and still present.

presence_identity_required

HTTP 400 · not retryable

Presence requests must carry both userId and organizationId.

project_slug_taken

HTTP 409 · not retryable

A project with this slug already exists in the organization. Choose a different slug.

queries_required

HTTP 400 · not retryable

The request must include a non-empty queries array.

query_invalid_boolean

HTTP 400 · not retryable

The query compared a boolean column against an invalid boolean literal.

query_invalid_identifier

HTTP 400 · not retryable

The query contained an invalid identifier.

query_invalid_like_pattern

HTTP 400 · not retryable

The LIKE pattern must not end with an escape character.

query_unknown_relation

HTTP 400 · not retryable

The query references a relation the model does not define. Check the relation name against the schema.

query_unsupported_operator

HTTP 400 · not retryable

The query used an unsupported operator.

replication_publication_drift

HTTP 400 · not retryable

Your schema maps to tables that are not members of the replication publication, so their changes silently never stream and the source looks frozen. The missing tables and the exact ALTER PUBLICATION … ADD TABLE … to add them are in the error details — Ablo never alters your database for you.

request_too_large

HTTP 413 · not retryable

The request body exceeds the maximum size.

schema_definition_invalid

client-only · not sent over the network

A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version).

schema_too_large

HTTP 413 · not retryable

The submitted schema exceeds the maximum size.

snapshot_reserved_key

HTTP 400 · not retryable

The snapshot uses a key name that is reserved by the runtime. Rename the key and retry.

source_adapter_misconfigured

client-only · not sent over the network

The data-source ORM adapter could not map a schema model onto the backing client — the client exposes no matching delegate or model. Check that the adapter and schema agree on model names.

source_event_invalid

HTTP 400 · not retryable

A data-source event was malformed — missing or invalid id, model, entityId, type, or field value. The whole event batch was rejected and nothing was ingested; fix the offending outbox row and re-send.

source_operation_id_required

client-only · not sent over the network

A data-source operation arrived without the entity id it targets.

task_id_required

HTTP 400 · not retryable

A task id is required for this request.

upload_fields_required

HTTP 400 · not retryable

The upload request is missing a required field.

upload_items_required

HTTP 400 · not retryable

The request must include a non-empty items array.

usage_invalid

HTTP 400 · not retryable

The usage request was invalid.

validation_failed

HTTP 400 · not retryable

The mutator rejected the input because it violates a business rule.

write_options_invalid

client-only · not sent over the network

The write options (idempotencyKey / label / wait / readAt / onStale / claim) failed validation against the write-options schema.

write_payload_invalid

client-only · not sent over the network

A write payload contained a value that cannot be represented safely as JSON. Use plain objects, arrays, finite numbers, strings, booleans, null, or valid dates.

Not found

The referenced resource does not exist (or is hidden by scope).

capability_not_found

HTTP 404 · not retryable

No capability exists with the given id.

claim_not_found

HTTP 404 · not retryable

No claim of yours exists with the given id. It was released, it expired, or it was never acquired on this plane.

entity_not_found

HTTP 404 · not retryable

No row exists with the requested id. It may have been deleted, or the id may belong to a different environment.

invalid_mutator

HTTP 404 · not retryable

The requested mutator is not registered on this server.

model_not_found

HTTP 404 · not retryable

No row of this model exists with the requested id. It may have been deleted, or the id may belong to a different environment.

mutate_update_entity_not_found

HTTP 404 · not retryable

The row targeted by this update does not exist — it may have been deleted since you read it. Re-read before retrying.

no_data_source_registered

HTTP 404 · not retryable

No database is connected to this plane yet, so there is nothing to check. Connect one with ablo connect apply, then run the check again.

Tenant / schema resolution

The named model could not be resolved in the tenant schema.

connected_database_unreachable

HTTP 503 · not retryable

Ablo could not reach the database connected to this environment: it refused the credentials on file, or did not answer at all. A database often changes after it is connected — a password is rotated, an instance is replaced — while the connection goes on pointing at what used to be there. The error names the host it tried. If the password changed, ablo connect rotate re-keys the roles and re-registers them; if the database itself was replaced, ablo connect apply sets up the new one and ablo connect register hands it over. Run either with a key for this environment.

model_not_provisioned

HTTP 409 · not retryable

This model is in the plane’s registered schema, but its table has not been provisioned yet. Registering a schema with ablo push records the model; a plane’s physical tables are created separately, out of band, so a model can appear in the schema before its table exists. Provision the plane’s tables, then retry the read.

model_not_tenant_scoped

HTTP 400 · not retryable

This model is not tenant-scoped, so it cannot be queried through the tenant-scoped read path.

mutate_create_unknown_model

HTTP 400 · not retryable

Created a model the server does not know. Run ablo push (or keep ablo dev running) to upload ablo/schema.ts first — the server keeps its own copy of the schema.

server_execute_unknown_model

HTTP 400 · not retryable

Wrote to a model the server does not know. The server keeps its own copy of the schema — run ablo push (or keep ablo dev running) to upload ablo/schema.ts before writing to new or changed models.

source_tenancy_not_enforced

HTTP 400 · not retryable

This model is scoped by its connected data source (policy: { by: 'source' }), so its tenant is resolved from the source registration rather than a row column. Enforcing that resolution requires the write-through connect path, which is not enabled on this plane yet — so the model cannot be served through the tenant-scoped read or bootstrap path without risking a cross-tenant read. If this model lives on a log plane, scope it with by: 'column' or by: 'parent' instead.

tenant_model_columns_unknown

HTTP 400 · not retryable

The columns for this model could not be resolved in the tenant database, so the operation cannot be mapped onto its table.

tenant_model_missing_organization_id

HTTP 400 · not retryable

This model’s table has no organization_id column, which Ablo requires to isolate rows by organization. Add the column before syncing this model.

unknown_model

HTTP 400 · not retryable

Named a model the server does not know. Run ablo push (or keep ablo dev running) to upload ablo/schema.ts — the server keeps its own copy of the schema.

user_scope_not_enforced

HTTP 400 · not retryable

Rows in this model belong to one person rather than to the whole organization, and that boundary is kept where the rows are stored. This plane is currently served from its log, which carries the organization and the project on every row but not the owner — so the boundary cannot be applied here, and serving the read would show one member another member’s private records. It was declined whole and nothing was returned. Serve the plane from its tables, or read with a credential that acts for the organization rather than for a person.

Schema

Schema declaration or migration problems.

drop_field

client-only · not sent over the network

This migration would drop an existing field, destroying the data stored in it.

drop_model

client-only · not sent over the network

This migration would drop an entire model and its table, destroying the rows stored in it.

enum_value_removed

client-only · not sent over the network

This migration removes an enum value that existing rows may still hold.

lossy_recreate

client-only · not sent over the network

This migration can only apply by recreating the table, which would not preserve its existing rows.

made_required

client-only · not sent over the network

This migration makes an existing optional field required, which rows without a value for it would violate.

query_relation_target_unknown

HTTP 500 · not retryable

A relation in the query targets a model the schema does not define.

required_field_added

client-only · not sent over the network

This migration adds a new required field that existing rows have no value for.

risky_cast

client-only · not sent over the network

This migration changes a column to a type its current values may not convert to cleanly.

schema_field_consecutive_caps

HTTP 400 · not retryable

A schema field name contains consecutive capital letters, which cannot be mapped to a column name unambiguously. Write acronyms in lower case (apiKey, not APIKey).

schema_field_not_camelcase

HTTP 400 · not retryable

A schema field name is not camelCase. Rename the field (for example dueDate) — Ablo derives column names from camelCase field names.

schema_grants_identifier_unsafe

HTTP 400 · not retryable

A grants declaration references an identifier that is not safe to use in SQL. Use plain column and relation names.

schema_grants_relation_kind

HTTP 400 · not retryable

A grants declaration references a relation of a kind it cannot traverse.

schema_grants_relation_missing

HTTP 400 · not retryable

A grants declaration references a relation the model does not define. Check the relation name against the model.

schema_grants_shape_invalid

HTTP 400 · not retryable

A grants declaration in the schema has an invalid shape and could not be parsed.

schema_grants_target_not_scope_root

HTTP 400 · not retryable

A grants declaration targets a model that is not a scope root, so access cannot be derived from it.

schema_mutable_missing_meta

HTTP 400 · not retryable

The schema is declared mutable but is missing its required meta block.

schema_reserved_field

client-only · not sent over the network

A model redeclared a reserved base field (id, createdAt, updatedAt, organizationId, createdBy) that the SDK provides automatically.

schema_scope_invalid

HTTP 500 · not retryable

The model’s scope predicate could not be built.

schema_scope_kind_invalid

HTTP 400 · not retryable

A scope declaration in the schema uses a kind the engine does not recognize.

schema_table_invalid

HTTP 500 · not retryable

The model’s table identifier is invalid.

Bootstrap

Initial snapshot fetch problems.

bootstrap_cancelled

client-only · not sent over the network

This bootstrap request was cancelled before it finished, because a newer one replaced it or the bootstrap it belonged to had already failed. It is not retried on its own.

bootstrap_fetch_timeout

HTTP 504 · retryable

The initial bootstrap fetch timed out before the server responded. Retry shortly.

bootstrap_offline

HTTP 503 · retryable

Bootstrap could not run because the client is offline. It can proceed once the network returns.

bootstrap_offline_no_cache

HTTP 503 · not retryable

The client is offline and no cached snapshot is available to start from, so there is no data to load until the network returns.

bootstrap_response_invalid

HTTP 502 · retryable

The bootstrap response could not be parsed. Retrying may succeed.

bootstrap_response_schema_invalid

HTTP 502 · retryable

The bootstrap response parsed but failed schema validation, so it was not applied. Retrying may succeed.

Transport

Network, connection, queue, and timeout failures. Generally retryable.

base_url_missing

client-only · not sent over the network

The client has no base URL configured, so it cannot address the server. Set the base URL when constructing the client.

commit_failed

HTTP 500 · retryable

The commit reached the server but failed to apply. Retrying may succeed.

commit_no_result

HTTP 504 · retryable

The commit was sent, but no result frame arrived, so its outcome is unknown. It is safe to retry.

commit_offline_grace_expired

HTTP 503 · not retryable

The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns.

data_source_blocked

HTTP 503 · not retryable

The plane’s data source is not in a verified, resolvable state. Fix its registration, secret, or configuration; Ablo will not fall through to hosted storage.

exchange_malformed_response

HTTP 502 · retryable

The credential exchange returned a response that could not be parsed. Retrying may succeed.

exchange_network_error

HTTP 503 · retryable

A network error interrupted the credential exchange. Check connectivity and retry.

fetch_unavailable

client-only · not sent over the network

This environment provides no fetch implementation, so HTTP requests cannot be made. Run on a platform with fetch (Node 18+, modern browsers) or supply a polyfill.

flush_timeout

HTTP 504 · retryable

Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes.

identity_network_error

HTTP 503 · retryable

A network error occurred while resolving your identity. Check connectivity and retry.

instance_at_capacity

HTTP 503 · retryable

The server is at connection capacity. Retry shortly — transient and not specific to your credentials.

malformed_response

HTTP 502 · not retryable

The server sent a message this client could not read, so it was declined whole rather than applied in part. Nothing was changed locally. This normally means the client and the server are running different versions; upgrading the client resolves it.

protocol_version_unsupported

HTTP 426 · not retryable

The client sync-protocol version is outside the range this server supports — upgrade the SDK (or the server was rolled back mid-fleet).

queue_too_deep

HTTP 503 · retryable

The line is already past its depth limit. For a claim, more participants were waiting than your maxQueueDepth allows — claim again without the cap to wait anyway, or work elsewhere and retry later. For a write, the transaction queue is draining — retry shortly.