Error reference

Every Homespun API error carries a stable code, an HTTP status, a short hint, a retryable flag, and a docs_url. The docs_url is the anchored entry on this page (https://docs.homespun.dev/reference/errors#<code>), so an agent that receives an error can follow it straight to the matching section.

This page is generated at build time from the relay error registry (packages/relay/src/http/errors.ts), so it can never drift from the codes the API actually returns. Sections are ordered by code.

account_quota_exceeded

HTTP 409 · client error · not retryable

account apps quota reached (max 100)

Hint. this cap applies across your whole account; delete unused apps/rows/attachments to free quota, or ask the operator to raise the matching MAX_*_PER_ACCOUNT limit (or upgrade the plan)

Remediation. This cap spans your whole account, not one app. Delete unused apps, rows, or attachments to free the tripped dimension, ask the operator to raise the matching MAX_*_PER_ACCOUNT limit, or upgrade the plan.

See also: CLI reference

agent_not_claimed

HTTP 403 · client error · not retryable

this agent must be claimed by a human before it can deploy an app

Hint. claim this agent first: open /get-started on the relay, generate a claim code, then run homespun agent claim <code> and retry the deploy

Remediation. Deploying an app needs a human owner. Ask a human to open /get-started and generate a claim code, then run homespun agent claim <code> and redeploy. Device-flow-registered agents are already claimed.

See also: Agent quickstart

app_not_found

HTTP 404 · client error · not retryable

Hint. the app id/slug is wrong, or the app does not belong to the calling agent’s owner; run ‘homespun apps list’ to find the right id

Remediation. The app id or slug is wrong, or the app belongs to another owner. Run homespun apps list to find an app you own and use its id.

See also: CLI reference

app_quota_exceeded

HTTP 409 · client error · not retryable

app rows quota reached (max 1000)

Hint. delete existing rows to free quota, or ask the operator to raise MAX_ROWS_PER_APP / MAX_STORAGE_BYTES_PER_APP

Remediation. The app hit its row or storage quota. Delete existing rows to free space, or ask the operator to raise MAX_ROWS_PER_APP / MAX_STORAGE_BYTES_PER_APP.

See also: CLI reference

append_only

HTTP 403 · client error · not retryable

collection ‘<collection>’ is append-only: rows cannot be updated or deleted

Hint. append-only collections accept create only, model an edit as a new row, or declare the collection with appendOnly:false in the manifest

Remediation. The collection is append-only: create rows only, never update or delete. Model an edit as a new row, or declare the collection with appendOnly:false in the manifest if edits are legitimate.

See also: Manifest reference

attachment_not_found

HTTP 404 · client error · not retryable

Hint. the attachment id is wrong, the attachment was deleted, or it does not belong to the calling agent; run ‘homespun attachment list’ to find the right id

Remediation. The attachment id is wrong, the attachment was deleted, or it belongs to another agent. Run homespun attachment list to find an id you own and reference that.

See also: CLI reference

attachment_ref_not_accessible

HTTP 422 · client error · not retryable

attachment ref(s) not accessible: <attachment_id>

Hint. the payload references one or more attachment ids the calling agent does not own (or that have been deleted); upload the attachment with POST /v1/attachments and use the returned attachment_id, or check ‘homespun attachment list’ for ids you actually own

Remediation. The payload references attachment ids the calling agent does not own or that were deleted. Upload the attachment (POST /v1/attachments) and use the returned attachment_id, or check homespun attachment list for ids you own. On the read side, an attachment is reachable only when it is referenced from this app events or initial input_data and is not soft-deleted.

See also: CLI reference

attachment_size_exceeded

HTTP 413 · client error · not retryable

attachment exceeds the per-attachment cap of 1048576 bytes

Hint. downscale or compress the attachment to fit; for images, the client SDK does this automatically (max dimension + JPEG quality)

Remediation. Shrink the attachment below the per-attachment cap. For images the client SDK downscales automatically (max dimension plus JPEG quality); otherwise compress or resize before uploading.

See also: CLI reference

attachment_token_invalid

HTTP 401 · client error · not retryable

Hint. the attachment token is unknown, expired, revoked, or has been spent (once-tokens); request a fresh token from the agent that owns the attachment

Remediation. Request a new attachment token from the agent that owns the attachment. Attachment tokens expire, can be revoked, and once-tokens are single-use, so a fresh token is the fix.

See also: Agent quickstart

attachment_token_not_found

HTTP 404 · client error · not retryable

Hint. the token id is wrong, or the token does not belong to this attachment; run ‘homespun attachment show <id>’ to list active tokens

Remediation. The token id is wrong or does not belong to this attachment. Run homespun attachment show <id> to list the attachment active tokens and use one of those.

See also: CLI reference

author_not_allowed

HTTP 403 · client error · not retryable

Hint. only the row author may perform this action

Remediation. Only the row author may perform this action. Act as the identity that created the row, or use an owner/agent path if one exists for the operation.

See also: Agent quickstart

capability_invalid

HTTP 400 · client error · not retryable

capabilities entry ‘<value>’ is invalid

Hint. capabilities must be an array of strings drawn from {camera, microphone, geolocation}, with no duplicates

Remediation. Set capabilities to an array of names drawn from the allowed list, with no duplicates. Remove the unknown value; the message lists the exact allowed names.

See also: Manifest reference

cli_upgrade_required

HTTP 426 · client error · not retryable

this relay requires @homespunapps/cli >= <min_version> (you sent <your_version>)

Hint. upgrade the @homespunapps/cli package to >= <min_version> and retry; non-CLI library callers can omit the x-homespun-cli-version header to opt out of this check

Remediation. Upgrade @homespunapps/cli to at least the required version and rerun. Library callers that are not the CLI can omit the x-homespun-cli-version header to opt out of the minimum-version check.

See also: CLI reference

collection_count_forbidden

HTTP 403 · client error · not retryable

reading the row count of collection ‘<collection>’ is not permitted for this principal

Hint. count requires one of: anyone

Remediation. The collection does not expose its count to your principal. Declare a countRead role list on the collection to opt into a count-only aggregate, then read the count as an allowed role.

See also: Manifest reference

collection_delete_forbidden

HTTP 403 · client error · not retryable

deleting from collection ‘<collection>’ is not permitted for this principal

Hint. delete requires one of: owner

Remediation. Your principal is not in the collection delete role list. Act as an allowed role, or widen the collection delete list in the manifest and redeploy.

See also: Manifest reference

collection_name_invalid

HTTP 400 · client error · not retryable

collection name ‘<name>’ is invalid

Hint. collection names must start with a lowercase letter and contain only lowercase letters, digits, ’_’, or ’-’ (max 64 chars)

Remediation. Rename the collection to start with a lowercase letter and use only lowercase letters, digits, _, or -, up to 64 characters.

See also: Manifest reference

collection_not_found

HTTP 404 · client error · not retryable

collection ‘<name>’ is not declared on this app

Hint. the collection name must match one declared in the app’s manifest (x-homespun-manifest.collections); redeploy with the collection declared, or check the name

Remediation. The collection is not declared on this app. Redeploy with the collection in x-homespun-manifest.collections, or correct the name to one that is declared.

See also: Manifest reference

collection_read_forbidden

HTTP 403 · client error · not retryable

reading collection ‘<collection>’ is not permitted for this principal

Hint. read requires one of: owner, agent

Remediation. Your principal is not in the collection read role list. Sign in as an allowed role (on a public app your page must call homespun.session.login()), or adjust the collection read list in the manifest.

See also: Manifest reference

collection_schema_invalid

HTTP 400 · client error · not retryable

the collection schema is invalid

Hint. schema must be { “$ref”: ”#/$defs/<Name>” }, resolve to an object under $defs, and compile as JSON Schema 2020-12

Remediation. A collection schema must be { "$ref": "#/$defs/<Name>" }, resolve to an object under $defs, and compile as JSON Schema 2020-12. Inline any sibling $defs ref (cross-$defs refs are not resolved) and keep each string maxLength within the per-row byte cap.

See also: Manifest reference

collection_write_forbidden

HTTP 403 · client error · not retryable

writing to collection ‘<collection>’ is not permitted for this principal

Hint. write requires one of: agent, owner

Remediation. Your principal is not in the collection write role list. Act as a role the collection allows to write, or widen the collection write list in the manifest and redeploy.

See also: Manifest reference

community_publish_disabled

HTTP 403 · client error · not retryable

Hint. publishing to the community gallery is disabled on this relay

Remediation. Publishing to the community gallery is turned off on this relay. Ask the operator to enable community publishing, or keep the app private or link-visible instead.

See also: Agent quickstart

conflict

HTTP 409 · client error · not retryable

Hint. the request conflicts with the current state of the resource

Remediation. The request conflicts with the resource current state. Re-read the resource, rebase your change on the latest version, and retry. For an optimistic-lock (if_match) mismatch, rebase against details.current and resend with its version.

See also: CLI reference

connection_invalid

HTTP 400 · client error · not retryable

a connection field is invalid

Hint. check the connection field named in the message: name is [a-z0-9][a-z0-9_-]{0,63}; allowedHost is a bare DNS host or a single leftmost ’*.’ wildcard; a static connection needs headerName + headerValue; oauth2 connections are created via the consent flow (a later build)

Remediation. Fix the connection field named in the message. name is [a-z0-9][a-z0-9_-]{0,63}; allowedHost is a bare DNS host or a single leftmost *. wildcard; a static connection needs headerName plus headerValue; oauth2 connections are created through the consent flow.

See also: CLI reference

connection_limit_reached

HTTP 409 · client error · not retryable

this app already has the maximum of 20 connections

Hint. delete an unused connection (DELETE /v1/apps/:id/connections/:name) before creating another, or ask the operator to raise MAX_CONNECTIONS_PER_APP

Remediation. The app is at MAX_CONNECTIONS_PER_APP. Delete an unused connection (DELETE /v1/apps/:id/connections/:name) before creating another, or ask the operator to raise the cap.

See also: CLI reference

connection_not_found

HTTP 404 · client error · not retryable

no connection named ‘<name>’ on this app

Hint. the connection name is wrong or it was deleted; list connections with GET /v1/apps/:id/connections

Remediation. No connection by that name exists on this app. List connections with GET /v1/apps/:id/connections and reference one that exists, or create it first.

See also: CLI reference

consent_owner_only

HTTP 403 · client error · not retryable

Hint. only the app owner may grant this consent

Remediation. Only the app owner may grant this consent. Have the owner complete the consent step in a browser; an agent key cannot grant it.

See also: Agent quickstart

csrf_origin_mismatch

HTTP 403 · client error · not retryable

Hint. the request Origin or Referer did not match the expected site origin

Remediation. The request Origin/Referer did not match the expected site origin. Issue the request from the app own page so the browser sends a matching origin, and do not strip these headers.

See also: Agent quickstart

custom_domains_not_enabled

HTTP 501 · server error · not retryable

custom domains are not enabled on this deployment

Hint. the relay operator has not configured Cloudflare for SaaS (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, CUSTOM_DOMAINS_CNAME_TARGET); ask them to enable it, or use the app’s built-in subdomain

See also: CLI reference

domain_exists

HTTP 409 · client error · not retryable

this app already has a custom domain (‘<domain>’)

Hint. an app can hold one custom domain; DELETE /v1/apps/:id/domain first to replace it

Remediation. An app holds one custom domain at a time. Send DELETE /v1/apps/:id/domain to remove the current one before adding another.

See also: CLI reference

domain_invalid

HTTP 400 · client error · not retryable

the domain is invalid

Hint. send a bare, valid DNS name you control (e.g. app.example.com) - platform domains and their subdomains, IP literals, wildcards, and local/reserved names are rejected

Remediation. Send a bare, valid DNS name you control (for example app.example.com). Platform domains and their subdomains, IP literals, wildcards, and local or reserved names are rejected.

See also: CLI reference

domain_not_found

HTTP 404 · client error · not retryable

Hint. this app has no custom domain; POST /v1/apps/:id/domain to add one

Remediation. This app has no custom domain configured. Send POST /v1/apps/:id/domain to add one.

See also: CLI reference

domain_taken

HTTP 409 · client error · not retryable

domain ‘<domain>’ is already in use

Hint. that domain is already bound to an app on this relay; remove it from the other app first, or use a different domain

Remediation. That domain is already bound to another app on this relay. Remove it from the other app first, or use a different domain.

See also: CLI reference

email_not_verified

HTTP 403 · client error · not retryable

Hint. verify your account email before performing this action

Remediation. Verify your account email before performing this action. Complete the verification link the relay sent, then retry.

See also: Agent quickstart

embed_invalid

HTTP 400 · client error · not retryable

embeds entry ‘<origin>’ is invalid: not an https origin

Hint. embeds entries must be https origins (an optional single leading ’*.’ wildcard is allowed when >= 2 labels remain), with no path/query/fragment/userinfo, no IP literals, no duplicates, and must not name the app’s own origin

Remediation. Give each embeds entry as an https origin with the same grammar as externalHosts (host only, optional single leading *. wildcard, no path, query, fragment, userinfo, or IP), no duplicates, and not the app own origin.

See also: Manifest reference

external_host_invalid

HTTP 400 · client error · not retryable

externalHosts entry ‘<host>’ is invalid: not an https origin

Hint. externalHosts entries must be https origins (an optional single leading ’*.’ wildcard is allowed when >= 2 labels remain), with no path/query/fragment/userinfo, no IP literals, no duplicates, and must not name the app’s own origin

Remediation. Give each externalHosts entry as an https origin (host only, an optional single leading *. wildcard with at least two remaining labels), with no path, query, fragment, userinfo, or IP literal, no duplicates, and not the app own origin.

See also: Manifest reference

forbidden

HTTP 403 · client error · not retryable

Hint. the authenticated identity is not permitted to perform this action

Remediation. The token is valid but this identity may not perform the action. Confirm you are acting as the app owner or owning agent, and that the target collection or resource permits your role.

See also: Agent quickstart

gone

HTTP 410 · client error · not retryable

app is closed

Hint. the app is closed or expired and cannot accept new events; create a new app to continue

Remediation. The app is closed or expired and cannot accept new events. Deploy or create a new app and send new traffic there.

See also: CLI reference

grant_invalid

HTTP 401 · client error · not retryable

Hint. the grant is missing, already used, expired, or was minted for a different app; restart sign-in via GET /authorize

Remediation. The session grant is missing, already used, expired, or minted for a different app. Restart sign-in from GET /authorize (homespun.session.login() does this for a page) to obtain a fresh grant.

See also: Agent quickstart

ingest_invalid

HTTP 400 · client error · not retryable

an ingest rule is malformed

Hint. check the named ingest rule field against the x-homespun-manifest.ingest grammar (name is [a-z0-9][a-z0-9_-]{0,63} and unique in the app; collection must be declared; mode ∈ {append,upsert} and upsert requires upsertOn naming a collection unique field; map values and dedupeKey are dot-paths into the JSON body; handshake is ‘echo’; wake is a boolean)

Remediation. Fix the ingest rule field named in the message. name is [a-z0-9][a-z0-9_-]{0,63} and unique within the app, collection must be declared, and mode is append or upsert (upsert requires upsertOn naming one of the collection’s unique fields). map values and dedupeKey are dot-paths into the JSON body; handshake is echo; wake is a boolean.

See also: Manifest reference

ingest_not_found

HTTP 404 · client error · not retryable

Hint. the catch-hook URL is wrong (unknown hook, bad secret, or a disabled hook); copy the exact POST /v1/ingest/<hookId>/<secret> URL from the app’s inbound-hooks panel or rotate the secret

Remediation. The catch-hook URL is wrong: no such hook, a bad secret, or the hook was disabled (its rule was removed from the manifest). Both an unknown hook and a bad secret return this same 404 on purpose, so the endpoint is not an existence oracle. Copy the exact POST /v1/ingest/<hookId>/<secret> URL from the app’s inbound-hooks panel, or rotate the secret to get a fresh URL.

See also: CLI reference

ingest_payload_too_large

HTTP 413 · client error · not retryable

Hint. the inbound catch-hook body exceeds INGEST_MAX_BODY_BYTES (64 KiB by default); send a smaller payload

Remediation. Send a smaller body. The inbound catch-hook accepts at most INGEST_MAX_BODY_BYTES (64 KiB by default) per request; trim or split the payload to fit.

See also: CLI reference

ingest_signature_invalid

HTTP 401 · client error · not retryable

Hint. the inbound catch-hook requires a valid body signature and this request’s signature did not verify; provision the hook’s signing secret with `homespun ingest signing-secret set` and paste it into the provider’s webhook Secret field (for GitHub set the webhook content type to application/json)

Remediation. The catch-hook opted into signature verification (verify in the manifest) and the request’s signature did not verify. A missing signature header, a malformed header, a wrong signature, and a hook whose signing secret is not yet provisioned all return this same 401 on purpose, so the endpoint gives an attacker nothing. Provision the hook’s signing secret with homespun ingest signing-secret set and paste that value into the provider’s webhook Secret field (for GitHub, also set the webhook Content type to application/json). This request was NOT journaled, so it will not appear in the delivery log.

See also: CLI reference

ingest_unsupported_media_type

HTTP 415 · client error · not retryable

Hint. the inbound catch-hook accepts application/json only in v1; send Content-Type: application/json

Remediation. Send Content-Type: application/json. The inbound catch-hook accepts a JSON body only in v1; form-encoded, multipart, and other content types are rejected.

See also: CLI reference

ingest_write_unavailable

HTTP 503 · server error · retryable

the inbound delivery could not be stored: the app is at its row or storage quota

Hint. the app is temporarily full; the delivery was recorded as failed and no row was written. Retry later (the owner can free space by deleting rows or raising MAX_ROWS_PER_APP / MAX_STORAGE_BYTES_PER_APP), or the owner can replay it from the inbound-hooks panel once space frees.

Remediation. The app is at its row or storage quota, so the inbound delivery could not be stored. This is transient: the delivery was journaled as failed and no row was written, so back off and redeliver later. The app owner can free space (delete rows, or raise MAX_ROWS_PER_APP / MAX_STORAGE_BYTES_PER_APP) and replay the delivery from the inbound-hooks panel.

See also: CLI reference

input_schema_violation

HTTP 422 · client error · not retryable

Hint. the event does not satisfy the app’s event schema; check the event type and payload against the declared schema

Remediation. The initial input_data failed the target collection schema. Fix the fields named in details so the seed data validates, then redeploy or recreate.

See also: Manifest reference

invalid_request

HTTP 400 · client error · not retryable

Hint. the request body or parameters are malformed; check the field named in the message against the API spec

Remediation. Fix the malformed field named in the message and resend. Check the request body and query parameters against the endpoint shape (homespun <command> --help documents the CLI surface).

See also: CLI reference

manifest_incompatible_redeploy

HTTP 422 · client error · not retryable

Hint. the new manifest narrows the app’s current manifest in one or more places; either publish a manifest that’s a superset, or retry with force=true to proceed (a narrowed/removed collection is detached, not deleted)

Remediation. The new manifest narrows the app current one. Publish a manifest that is a superset of the live one, or retry with force=true to proceed, which detaches (never deletes) a narrowed or removed collection.

See also: Manifest reference

manifest_invalid

HTTP 400 · client error · not retryable

the manifest top-level shape is invalid

Hint. the manifest’s top-level shape is wrong; check the field named in the message against the x-homespun-manifest grammar

Remediation. Fix the manifest field named in the message. The top-level shape is wrong; validate your document against the x-homespun-manifest grammar (see the manifest reference) and redeploy.

See also: Manifest reference

manifest_too_large

HTTP 413 · client error · not retryable

the manifest exceeds the configured size limit

Hint. shrink the manifest (or the offending $defs row schema) below the configured MAX_MANIFEST_BYTES / MAX_SCHEMA_BYTES limit

Remediation. Shrink the manifest below MAX_MANIFEST_BYTES, or the offending $defs row schema below MAX_SCHEMA_BYTES. Remove unused $defs, flatten deep nesting, and trim long descriptions.

See also: Manifest reference

method_not_allowed

HTTP 405 · client error · not retryable

Hint. the request HTTP method is not supported on this route; see the Allow response header for the verbs that are

Remediation. Use one of the HTTP verbs the route supports. The response Allow header lists the verbs that are valid on this path.

See also: CLI reference

mime_disallowed

HTTP 415 · client error · not retryable

MIME ‘<mime>’ is not in this relay’s BLOB_MIME_ALLOWLIST

Hint. upload a file matching one of the allowed MIME prefixes; ask the operator to widen BLOB_MIME_ALLOWLIST if a missing prefix is legitimate

Remediation. Upload a file whose sniffed MIME is in the relay BLOB_MIME_ALLOWLIST. Convert the file to an allowed format, or ask the operator to add the prefix if it is legitimate.

See also: CLI reference

mime_mismatch

HTTP 415 · client error · not retryable

declared Content-Type ‘<declared>’ does not match the sniffed ‘<sniffed>’

Hint. send a Content-Type that matches the file’s actual format; the server validates leading bytes and refuses the upload on mismatch

Remediation. Send a Content-Type that matches the file real bytes. The relay sniffs the leading bytes and refuses an upload whose declared type disagrees; re-detect the type or re-encode the file.

See also: CLI reference

not_a_reviewer

HTTP 403 · client error · not retryable

Hint. only a designated reviewer may perform this action

Remediation. Only a designated reviewer may perform this action. Ask an owner to grant the reviewer role, or act as an identity that already holds it.

See also: Agent quickstart

not_found

HTTP 404 · client error · not retryable

Hint. the resource id may be wrong, or the resource was cleaned up; verify the id and try again

Remediation. Verify the resource id. Ids come back from the create call and the relevant list command; a resource that was cleaned up or never existed reads the same way.

See also: CLI reference

not_implemented

HTTP 501 · server error · not retryable

<capability> is not implemented on this relay

Hint. this relay does not implement the requested capability

See also: CLI reference

notify_invalid

HTTP 400 · client error · not retryable

a notify rule is malformed

Hint. check the named notify rule field against the x-homespun-manifest.notify grammar (on ∈ {create,update}; collection must be declared; to is a non-empty array of roles {owner, members}; subject/body are plain-text templates)

Remediation. Fix the notify rule field named in the message. on is create or update, collection must be declared, to is a non-empty array of roles ({owner, members}), and subject/body are plain-text templates. See the manifest reference notify section.

See also: Manifest reference

notify_submitter_not_enabled

HTTP 400 · client error · not retryable

notify rule on collection ‘<collection>’ targets the ‘submitter’ role, but external (submitter) sending is not enabled on this relay

Hint. Phase 1 supports the ‘owner’ and ‘members’ roles only. External submitter/customer-confirmation emails are a later phase; remove ‘submitter’ from `to`, or ask the operator to enable NOTIFY_EXTERNAL_ENABLED once that phase ships.

Remediation. External submitter emails are disabled on this relay. Remove submitter from the rule to (use owner or members), or ask the operator to enable NOTIFY_EXTERNAL_ENABLED once that phase ships.

See also: Manifest reference

participant_token_invalid

HTTP 401 · client error · not retryable

Hint. the participant token is unknown, malformed, or revoked; the agent can mint a fresh one via POST /v1/apps or by revoking + re-creating the app

Remediation. Mint a fresh participant token. The current one is unknown, malformed, or revoked; create a new app (POST /v1/apps), or revoke and recreate, then hand the browser the new token.

See also: Agent quickstart

payload_too_large

HTTP 413 · client error · not retryable

Hint. the payload exceeds the configured size cap (MAX_ARTIFACT_BYTES for templates, MAX_EVENT_DATA_BYTES for event data, MAX_TASTE_BYTES for taste notes); send a smaller payload

Remediation. Send a smaller payload. The relevant cap is MAX_ARTIFACT_BYTES (templates), MAX_EVENT_DATA_BYTES (event data), or MAX_TASTE_BYTES (taste notes); split or trim the content to fit.

See also: CLI reference

permission_role_invalid

HTTP 400 · client error · not retryable

a permission role is invalid

Hint. write/delete must be non-empty arrays drawn from {agent, owner, member, anyone, author}: ‘author’ is never valid in write

Remediation. Set each of write and delete to a non-empty array drawn from {agent, owner, member, anyone, author}. author is never valid in write, since a create has no prior row to attribute.

See also: Manifest reference

purge_forbidden

HTTP 403 · client error · not retryable

Hint. only the app owner or owning agent may purge a row

Remediation. Only the app owner or the owning agent may purge a row. Purge bypasses the append-only rule and the collection delete list on purpose, so it is restricted to owner/agent; act as one of those, or use a normal delete where the collection permits it.

See also: Agent quickstart

quota_exceeded

HTTP 413 · client error · not retryable

agent attachment quota of 1048576 bytes reached

Hint. delete unused attachments in this scope and retry, or ask the operator to widen the configured quota

Remediation. The per-scope attachment quota is full. Delete unused attachments in this scope (agent or app) and retry, or ask the operator to raise the configured quota.

See also: CLI reference

rate_limited

HTTP 429 · client error · retryable

Hint. the rate limit was exceeded; wait before retrying, back off and try the request again

Remediation. Back off and retry after a short pause. This limiter is per IP over a rolling window; honour any Retry-After hint, add jitter, and avoid tight retry loops.

See also: Manifest reference

resync_required

HTTP 410 · client error · not retryable

the requested feed cursor is below the retention floor; resync from a full collection snapshot

Hint. drop the since cursor and re-list each collection (GET …/collections/:name), then resume watching from the newest feed cursor

Remediation. Your feed cursor is below the retention floor, so a contiguous replay is impossible. Drop the since cursor, re-list each collection for a full snapshot, then resume watching from the newest feed cursor.

See also: CLI reference

row_not_found

HTTP 404 · client error · not retryable

no row at key ‘<key>’ in collection ‘<collection>’

Hint. the row may have been deleted, or the key is wrong; list the collection to see current rows

Remediation. No live row exists at that key (soft-deleted rows read as absent). List the collection to see current keys, or create the row first.

See also: CLI reference

row_schema_violation

HTTP 422 · client error · not retryable

Hint. the event does not satisfy the app’s event schema; check the event type and payload against the declared schema

Remediation. The row data failed the collection JSON Schema. The failing schema paths are listed in the error details; correct those fields and retry. A non-conforming write never lands.

See also: Manifest reference

schedule_invalid

HTTP 400 · client error · not retryable

a schedules rule is malformed

Hint. check the named schedules rule field against the x-homespun-manifest.schedules grammar (collection must be declared; dateField a field of it; offsetDays an integer, negative = before / 0 = on / positive = after; to is a non-empty array of {owner, members}; when is an optional level condition; subject/body are plain-text templates)

Remediation. Fix the schedules rule field named in the message. collection must be declared, dateField a field of it, offsetDays an integer (negative before, 0 on, positive after), to a non-empty array of {owner, members}, and subject/body plain-text templates.

See also: Manifest reference

schema_incompatible_upgrade

HTTP 422 · client error · not retryable

Hint. the target template version narrows the app’s current schema in one or more places; either publish a wider template version that’s a superset, or retry with compat=“force” to skip the gate (events written under the old schema may no longer validate)

Remediation. The target template version narrows the app current schema, so past events might stop validating. Publish a wider template version that is a superset, or retry with compat="force" to accept the narrowing.

See also: Manifest reference

schema_violation

HTTP 422 · client error · not retryable

Hint. the event does not satisfy the app’s event schema; check the event type and payload against the declared schema

Remediation. The event or row does not satisfy the collection declared JSON Schema. Read the failing paths in details, correct the payload to match the schema, and resend. A schemaless collection accepts any shape.

See also: Manifest reference

slug_not_allowed_for_link

HTTP 400 · client error · not retryable

a caller-supplied slug is not allowed with visibility ‘link’

Hint. either drop visibility ‘link’ (new apps default to private, which accepts an owner-chosen slug) or omit --slug to let the relay generate an unguessable link slug

Remediation. Link-visibility slugs are always server-generated and unguessable. Drop visibility link (new apps default to private, which accepts your slug), or omit --slug to let the relay mint the link slug.

See also: CLI reference

slug_taken

HTTP 409 · client error · not retryable

slug ‘<slug>’ is already in use

Hint. choose a different --slug, or omit it to let the relay generate one

Remediation. Another app already uses that slug. Choose a different --slug, or omit it and let the relay generate an unused one.

See also: CLI reference

soft_deleted

HTTP 410 · client error · not retryable

<entity> is in trash

Hint. restore the <entity> from trash (POST /v1/trash/<entity>s/:id/restore) before mutating it, or use ?include_deleted=true on read-only endpoints to see its current state

Remediation. The row is in trash and recoverable until the sweeper reclaims it. Restore it (POST /v1/trash/<entity>s/:id/restore) before mutating, or pass ?include_deleted=true on read-only endpoints to inspect it.

See also: CLI reference

too_many_collections

HTTP 400 · client error · not retryable

manifest declares 99 collections, exceeding the limit of 50

Hint. reduce the number of declared collections, or ask the operator to raise MAX_COLLECTIONS_PER_APP

Remediation. Declare fewer collections, or ask the operator to raise MAX_COLLECTIONS_PER_APP. Consider whether some collections can merge into one with a discriminator field.

See also: Manifest reference

too_many_embeds

HTTP 400 · client error · not retryable

manifest declares 99 embeds entries, exceeding the limit of 50

Hint. reduce the number of embeds entries, or ask the operator to raise MAX_EMBEDS

Remediation. List fewer embeds, or ask the operator to raise MAX_EMBEDS. Only origins you iframe need to be declared.

See also: Manifest reference

too_many_external_hosts

HTTP 400 · client error · not retryable

manifest declares 99 externalHosts entries, exceeding the limit of 50

Hint. reduce the number of externalHosts entries, or ask the operator to raise MAX_EXTERNAL_HOSTS

Remediation. List fewer externalHosts, or ask the operator to raise MAX_EXTERNAL_HOSTS. Only origins your page actually fetches from need to be declared.

See also: Manifest reference

unauthorized

HTTP 401 · client error · not retryable

Hint. the request needs a valid bearer token: an agent API key for /v1 endpoints, or a participant token for /s endpoints

Remediation. Attach a valid bearer token. For /v1 agent endpoints send your agent API key (register once with homespun agent register); for /s participant endpoints send the participant token the app minted. A missing or mistyped Authorization header is the usual cause.

See also: Agent quickstart

unique_backfill_conflict

HTTP 409 · client error · not retryable

cannot add a unique constraint on ‘<field>’ to collection ‘<collection>’: two or more existing live rows already share a value for ‘<field>’

Hint. resolve the existing duplicates first: delete or edit the colliding rows so every live row holds a distinct ‘<field>’ value (compared after trimming and case-folding), then redeploy with ‘<field>’ in the collection’s ‘unique’ list

Remediation. Adding unique to a collection that already holds duplicate values for that field is refused, so the constraint is never half-applied. Find the live rows that share a value (compared after trimming and case-folding), delete or edit all but one so every live row holds a distinct value, then redeploy with the field in unique.

See also: Manifest reference

unique_conflict

HTTP 409 · client error · not retryable

a row with this ‘<field>’ already exists in collection ‘<collection>’

Hint. ‘<field>’ is declared unique on this collection; use a different value, or upsert on ‘<field>’ (POST with { on: ‘<field>’, data }) to update the existing row instead of creating a duplicate

Remediation. The collection declares this field as unique, and another live row already holds this value (values are compared after trimming and case-folding). Use a different value, or upsert on this field (--on <field>) to update the existing row in place instead of creating a duplicate.

See also: CLI reference

unknown_event_type

HTTP 422 · client error · not retryable

Hint. the event does not satisfy the app’s event schema; check the event type and payload against the declared schema

Remediation. The event type is not one the app schema declares. Send an event whose type matches the declared schema, or widen the schema to cover it.

See also: Manifest reference

upload_forbidden

HTTP 403 · client error · not retryable

Hint. this identity may not upload to this app

Remediation. This identity may not upload to this app. Confirm you are the owner or owning agent, and that the app permits uploads for your role.

See also: Agent quickstart

webhook_invalid

HTTP 400 · client error · not retryable

a webhooks rule is malformed

Hint. check the named webhooks rule field against the x-homespun-manifest.webhooks grammar (on ∈ {create,update}; collection must be declared; when is an optional level/edge condition; url must be a public https target with no userinfo and no IP literal)

Remediation. Fix the webhooks rule field named in the message. on is create or update, collection must be declared, and url must be a public https target with no userinfo and no IP literal. when is an optional level or edge condition.

See also: Manifest reference