API error codes

Every refusal from the participant API (/v1) and the management API (/management/v1) carries a stable machine-readable code beside its human-readable message. Branch on code and the HTTP status, never on the message: messages are prose and may change in any release.

The error body

{
  "error": "Complete the required quests first",
  "code": "prerequisites-incomplete",
  "missing": [
    {
      "kind": "completion",
      "quest": "join",
      "title": "Join the waitlist",
      "scope": "ever"
    }
  ]
}

Each client reads the same body:

• Participant client: a RelayError with code and, for prerequisites, missing. RelayErrorCode from @domino-sdk/relay names the codes participant apps branch on most.
• Management client: a ManagementError with code, and the other fields in details. managementErrorSchema from @domino-sdk/relay/server parses the body of a raw api.raw() answer.
• CLI: with --json, the error's apiCode (see the CLI automation contract).

code is an open string. Relay adds codes in minor releases, so handle a code you do not know by its HTTP status. A few codes from earlier releases are upper case, such as PROJECT_MOVED and the identity exchange's INVALID_IDENTITY_EXCHANGE; they keep their spelling.

Keep uncertain writes pending

After refreshing and confirming the outcome of a write that requires reconciliation, call the helper's settle(). Console offers I have confirmed the result for that acknowledgment. Do not acknowledge a result that is still unknown; starting another write can apply it twice.

Use createRelayAction() from @domino-sdk/relay to retain the callback and key for a management write, such as action.run((actionId) => management.points.record({ actionId, kind: "award", member, balance, amount: 10, reason: "Welcome" })). Keep the helper until a definite result. Its retry() sends the original input again only when the error has recovery: "replay"; it waits any remaining retryAfter. A new key starts a new write even if its other fields are identical. See Retry after an uncertain answer for helper lifetime, reconciliation, and React usage.

Console shows uncertain writes with their operation ID. Offer controls and redemption refunds, member point changes and reversals, stock changes, and entitlement corrections offer Retry the same change. The retry uses the original input and key, even if the form has since changed. Writes without replay-safe receipts instruct the operator to refresh and inspect the result first.

Codes by status

A refusal with nothing more specific to say answers with its status's code:

A refusal that follows a write which may have taken effect answers 502 instead of 503 and keeps its code, such as unavailable: decide on retrying from the status.

Invalid input names its fields. A request body or query that fails validation answers 400 invalid-request with the fields it refused in error, such as Invalid request: actionId, records.0.occurredAt (at most five, then "and N more"). The message names fields only, never the values sent. The SDK clients check input before sending and reject with invalid-input, giving each field and its reason on one line: Invalid management request: actionId: use 1–100 letters, digits, _ or - (no :, . or spaces). actionId follows that rule, so build a retry-stable one from a hex hash rather than joining IDs with :.

Large request bodies. A management write counts the JSON values in its body (each array, object, key, string, number and literal) and refuses one with too many with 413 payload-too-large before reading it: more than 2,000,000 on bulk writes (catalog deploys, previews and drafts, deployment previews, release batches, tracker record ingest and member import rows, each up to 64 MB) and more than 500,000 on other writes. Split the batch. A Relay server handles one body over 4 MiB or 500,000 values at a time; another one waits up to 10 seconds, then answers 503 unavailable with Retry-After before doing anything. The CLI and the SDK clients send any call again after such a 503, within the call's deadline.

Routing, scope and identity exchange

Reload, then try again

The state changed since the caller read it. Nothing was written. Read the current state, then retry or show it.

The participant API describes the participant client's reload behavior.

Sign in or use another credential

Access describes each kind of credential, the roles behind it and what it may do in live.

Participant sign-in adds its own:

Discord verification configuration

An attempt that cannot verify Discord because the project has no ready connection or the bot's access was removed becomes failed with code: "integration-required" when quest code lets the capability error escape. Its reason explains the configuration problem without provider details. Relay does not automatically retry this deterministic failure. Connect or repair Discord in Console Integrations, in the same project and environment, before an explicit retry. domino attempts get <attempt> includes the code and reason. Publication doesn't refuse these quests: they publish, and a deployment's preview and result name them in warnings with code integration-required (printed by domino deploy). Connecting or repairing Discord admits the automatic attempts that failed this way again, for automatic quests without a tracker; tracker-triggered attempts need an explicit retry. Temporary outages remain retryable provider-unavailable capability errors.

Participation

Offers have their own refusal codes:

Analytics queries (domino analytics query, management.analytics.query) answer 422 with these codes; see metric catalog:

A deployment, preview or staging activation whose badge, point ledger, offer, leaderboard, referral, dashboard or tracker fails its schema answers 422 validation-failed naming the kind, key and field, such as Offer "ladder" is invalid: stock: Invalid input: expected number, received undefined. domino check reports the same failure first as a DEFINITION_INVALID diagnostic with the entry file, export and path.

Dashboard deployments (domino deploy with dashboards in relay.json) answer 422 with these codes; see dashboards:

A dashboard read gives a failing panel its own error instead of failing: group-not-found, panel-timeout when its query ran too long, or panel-failed for any other failure. Unarchiving a dashboard when the project already has 20 that aren't archived answers 422 too-many-dashboards.

Configuration and project state

Operator corrections and retired operations

inventory-in-use refuses item archive while any retained offer, including a paused or archived offer, or pickup variant references it. The response's offers and pickups arrays identify the blockers. An offer's backing item therefore cannot be archived; archive the offer instead. Reconfigure pickup references away from the item first. inventory-archived refuses new allocations, restocking and pickup configuration against an archived item; unarchive it first.

New operator corrections also return: