API error codes — the complete catalog

ObjectStack uses a structured error system with 9 error categories and 56 error codes reachable on the wire. Every error includes a machine-readable code, HTTP status mapping, and retry guidance.

This catalog documents the wire face — the codes a client can actually receive. That is not quite the StandardErrorCode enum: the enum also carries in-process spellings the REST door translates at the boundary, and the catalog carries error-code ledger codes the enum does not. A translated code is documented under the spelling clients receive, and named in that entry's cross-reference sentence so the in-process one stays findable.

Error Categories

Retry Strategies

Validation Errors (400)

VALIDATION_ERROR

Cause: Generic validation failure — request body does not match expected schema.
Fix: Check the fields array for specific field-level issues.
Retry: no_retry

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "category": "validation",
  "httpStatus": 400,
  "retryable": false,
  "fields": [
    { "field": "email", "message": "Invalid email format", "code": "invalid_email" }
  ]
}

API_KEY_EXPIRY_TOO_LONG

Cause: POST /api/v1/keys asked for an expires_at further away than the deployment's maximum key lifetime (api_key_max_expiry_days, one year by default). The message names the latest date allowed; exactly the maximum is accepted.
Fix: Ask for that date or an earlier one, and rotate the key before it expires.
Retry: no_retry

VALIDATION_FAILED

Cause: Record-level validation refused the write. This is the code a producer names — ValidationError from the record and rule validators, and any error of the same shape (code: 'VALIDATION_FAILED' / name: 'ValidationError') — as opposed to VALIDATION_ERROR above, which is derived from the status when the producer named no code at all. It covers required, type, format, length, range and picklist violations, a dangling lookup / master_detail reference (fields[].code === 'reference_not_found' — see the callout below), a malformed expectedVersion / If-Match token, and a batch row that names no record id.
Fix: Branch on this code and read fields[]. Each entry carries field (the API name, so a form can focus the right input), code from the field-level catalog (ADR-0114), a message rendered in the caller's locale, and — where they apply — label, constraint, value and options. Correct the named values and resend; no retry of the same payload can succeed.
Retry: no_retry

{
  "error": "Email is not a valid email address",
  "code": "VALIDATION_FAILED",
  "fields": [
    { "field": "email", "code": "invalid_format", "label": "Email",
      "message": "Email is not a valid email address" }
  ]
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Email is not a valid email address",
    "httpStatus": 400,
    "details": { "fields": [{ "field": "email", "code": "invalid_format" }] }
  }
}

INVALID_FIELD

Cause: A field name in the request does not exist on the target object. On a list read this also covers an unreserved query parameter — GET /data/:object reads those as field filters, so one naming no field could only match zero records and is rejected rather than answered with an empty page — plus every other read axis that names a field: select, expand (a real field that holds no reference gets its own message), searchFields (a real field outside the searchable set gets its own message, and so does a value with the wrong shape — an array entry that is not a string, or a value that is itself neither a comma-separated string nor an array of field names), groupBy, and aggregations[].field. The same code also refuses a field that DOES exist but is declared internal: true, when a read names it in a position that would evaluate its stored value: a filter (including a condition on a related object reached through a lookup, and an aggregation's own filter), a sort, a groupBy, an aggregations[].field, a searchFields entry, or an expand entry's own filter or sort at any depth. Such a field is never returned on a generic read, so it cannot be queried by either — the refusal names the object that declares it. Query by another field. Off the request path the same code answers backfillSummaryNulls's recomputeUndefinedOnEmpty (os migrate summary-nulls --recompute-undefined-on-empty object.field) when an entry is not a roll-up owned by an object the run walks — a typo, a real non-summary field, or a roll-up on an object --object left out are refused alike, one message naming every unresolved entry and how many objects the run walked.
Fix: Check the object schema for valid field names. Use os meta get object <name> to inspect the object's fields. If the name was meant as a parameter rather than a field, use the real one — page size is top / $top / limit, not pageSize / perPage; the response's error names the substitute. See the Data API.
Retry: no_retry

MISSING_REQUIRED_FIELD

Cause: A required field was not provided in the request body.
Fix: Include the missing field. Check fields for the field name — except on the controlled_by_parent master-reference paths below, where the status is 422 and no fields array is sent; read the field name out of the message there.
Retry: no_retry

INVALID_FORMAT

Cause: Reserved for a value that does not match an expected format. No route emits it today. A malformed value is refused as a field-level failure inside VALIDATION_FAILED instead, and its fields[].code names what checked it:

• the field's type — an email, url or phone field runs a built-in shape check keyed on type itself and answers invalid_email / invalid_url / invalid_phone; a value a date, datetime or time field cannot parse answers invalid_date / invalid_time;
• a format validation rule — its regex, or its named format (email | url | phone | json) — answers invalid_format.

A value that misses a declared pattern outside record metadata (a settings value, a request body a route parses with Zod) also answers field-level invalid_format.
Fix: Do not branch on this code; branch on VALIDATION_FAILED + fields[].code. To change what a field accepts, change its type or the format validation rule — a field-level format key runs no write-time check on any field type, so editing it changes nothing.
Retry: no_retry

VALUE_TOO_LONG

Cause: Reserved for a string value longer than its declared maximum. No route emits it today. A length miss is refused as a field-level max_length entry instead, and where that entry rides depends on what was written:

• a record write (a string over a field's maxLength) and a request body a route parses with Zod answer 400 VALIDATION_FAILED with the entry in fields[] — top-level on the /data routes, under details when the runtime dispatcher serves it (see VALIDATION_FAILED); on a record write its constraint carries maxLength and the actual length;
• a settings write (a value over its declared maximum) answers 400 SETTINGS_VALIDATION with the entry in details.fields[].

Fix: Do not branch on this code; branch on VALIDATION_FAILED + fields[].code max_length, or on SETTINGS_VALIDATION + details.fields[].code max_length for a settings write, and shorten the value to fit the declared maximum.
Retry: no_retry

VALUE_TOO_SHORT

Cause: Reserved for a string value shorter than its declared minimum. No route emits it today. A length miss is refused as a field-level min_length entry instead, and where that entry rides depends on what was written:

• a record write (a string under a field's minLength) and a request body a route parses with Zod answer 400 VALIDATION_FAILED with the entry in fields[] — top-level on the /data routes, under details when the runtime dispatcher serves it (see VALIDATION_FAILED); on a record write its constraint carries minLength and the actual length;
• a settings write (a value under its declared minimum) answers 400 SETTINGS_VALIDATION with the entry in details.fields[].

Fix: Do not branch on this code; branch on VALIDATION_FAILED + fields[].code min_length, or on SETTINGS_VALIDATION + details.fields[].code min_length for a settings write, and lengthen the value to meet the declared minimum.
Retry: no_retry

VALUE_OUT_OF_RANGE

Cause: Numeric value is outside the field's min/max range.
Fix: Ensure the value is within the allowed range.
Retry: no_retry

INVALID_REFERENCE

Cause: Reserved for an invalid foreign-key reference. No route emits it today. A lookup / master_detail pointing at a record that does not exist is refused as a field-level failure instead — see below.
Fix: Do not branch on this code; branch on VALIDATION_FAILED + fields[].code === 'reference_not_found'.
Retry: no_retry

{
  "error": "User: no sys_user record has id \"usr_missing\"",
  "code": "VALIDATION_FAILED",
  "fields": [{
    "field": "user_id",
    "code": "reference_not_found",
    "label": "User",
    "constraint": { "target": "sys_user" },
    "value": "usr_missing"
  }]
}

DUPLICATE_VALUE

Cause: A field with unique: true already has a record with the same value.
Fix: Use a different value or update the existing record.
Retry: no_retry

INVALID_QUERY

Cause: A groupBy / aggregations value the spec cannot read: a bare string where an array belongs, an entry that names no field, an aggregation function or dateGranularity outside the spec's enums, or a missing alias. (Field names that simply don't exist on the object are INVALID_FIELD instead.)
Fix: Check the aggregation shapes against the Query Cheat Sheet — e.g. { "groupBy": ["status"], "aggregations": [{ "function": "sum", "field": "amount", "alias": "total" }] }. count is the only function that may omit field.
Why it is an error and not an empty result: every one of these shapes used to be silently ignored or mis-read — rows came back ungrouped, or an unknown function computed null — in a response indistinguishable from a served aggregation.
Retry: no_retry

INVALID_FILTER

Cause: The server could not turn the request's filter into something it can run. Covers an invalid operator or field in the where clause, a $filter array that is not a filter AST (a bad operator, a lone ["and"]), a filter query parameter that is not valid JSON, and JSON that parses to something that is not a filter (5, "done", null).
Fix: Use valid filter operators ($eq, $ne, $gt, $lt, $in, $contains, etc.) and a filter shape the Data API accepts — an object, or an array of [field, operator, value] conditions. The error message names the offending element.
Why it is an error and not an empty result: a filter the server cannot run is never silently skipped, because skipping it would return the unfiltered result set — a response indistinguishable from a successful query.
Retry: no_retry

INVALID_SORT

Cause: The orderBy clause references a non-existent or non-sortable field.
Fix: Ensure the field exists and has sortable: true.
Retry: no_retry

MAX_RECORDS_EXCEEDED

Cause: The request attempts to create or return more records than the system limit.
Fix: Use pagination (limit/offset or cursor-based) for large datasets. Batch operations for bulk creates.
Retry: no_retry

Authentication Errors (401)

UNAUTHENTICATED

Cause: No authentication credentials were provided.
Fix: Include a valid Authorization header (Bearer token, API key, or session cookie).
Retry: no_retry

INVALID_CREDENTIALS

Cause: Username/password combination is incorrect.
Fix: Verify credentials and try again. After multiple failures, account may be locked.
Retry: no_retry

EXPIRED_TOKEN

Cause: The authentication token (JWT, session token) has expired.
Fix: Obtain a new token using the refresh token endpoint or re-authenticate.
Retry: retry_immediate (after refreshing token)

INVALID_TOKEN

Cause: The authentication token is malformed or has been tampered with.
Fix: Obtain a fresh token from the authentication endpoint.
Retry: no_retry

SESSION_EXPIRED

Cause: The user session has timed out due to inactivity.
Fix: Re-authenticate to start a new session.
Retry: no_retry

MFA_REQUIRED

Cause: Multi-factor authentication is required but the MFA challenge has not been completed.
Fix: Complete the MFA verification step before proceeding.
Retry: no_retry

EMAIL_NOT_VERIFIED

Cause: The user's email address has not been verified.
Fix: Complete email verification through the link sent to the user's email.
Retry: no_retry

Authorization Errors (403)

PERMISSION_DENIED

Cause: The authenticated user does not have permission for this operation.
Fix: Request the necessary permissions from an administrator, or use an account with the required role.
Retry: no_retry

INSUFFICIENT_PRIVILEGES

Cause: The user has some access but lacks the specific privilege required for this action.
Fix: Contact an administrator to grant the necessary privilege.
Retry: no_retry

FIELD_NOT_ACCESSIBLE

Cause: The user does not have access to a specific field on the object.
Fix: Remove the inaccessible field from the request, or request field-level access.
Retry: no_retry

RECORD_NOT_ACCESSIBLE

Cause: The user cannot access this specific record due to record-level sharing rules.
Fix: Request access to the record from its owner or an administrator.
Retry: no_retry

LICENSE_REQUIRED

Cause: The feature requires a specific license that is not active.
Fix: Upgrade the license or contact your administrator.
Retry: no_retry

IP_RESTRICTED

Cause: The request originates from an IP address that is not in the allowlist.
Fix: Ensure the request comes from an approved IP range, or update the IP restriction settings.
Retry: no_retry

TIME_RESTRICTED

Cause: Access is limited to specific time windows and the current time is outside the allowed range.
Fix: Retry during the allowed time window.
Retry: retry_after

API_KEY_EXPIRED

Cause: The API key is past its expires_at, or it was created with no expiry and the one-year grace the API-key lifecycle policy gave it has ended. The message names the key's prefix and the date.
Fix: Keys do not renew: create a new key and replace this one wherever it is configured. See key lifetime, inactivity and rotation.
Retry: no_retry

API_KEY_INACTIVE

Cause: The API key has no recorded use for longer than the deployment's inactivity window (api_key_inactivity_days, 90 by default). The key is not revoked; its own call does not revive it. The message names the date the idle period started.
Fix: Create a new key and replace this one wherever it is configured.
Retry: no_retry

API_KEY_REVOKED

Cause: The API key was revoked by its owner or an administrator.
Fix: Create a new key and replace this one wherever it is configured. A revoked key never works again.
Retry: no_retry

These three are answered on every endpoint that accepts an API key: the endpoints the runtime serves (the MCP HTTP endpoint among them), the REST data API, the settings, file-download, datasource admin and share-link routes, the marketplace install routes and the MCP stdio transport. An unknown key is always the generic 401.

Not Found Errors (404)

RESOURCE_NOT_FOUND

Cause: The requested resource does not exist (generic).
Fix: Verify the resource identifier and endpoint path.
Retry: no_retry

OBJECT_NOT_FOUND

Cause: The specified object (table/entity) does not exist in the schema.
Fix: Check the object name. Use os meta list object to list available objects.
Retry: no_retry

RECORD_NOT_FOUND

Cause: No record exists with the given ID in the specified object.
Fix: Verify the record ID. The record may have been deleted.
Retry: no_retry

FIELD_NOT_FOUND

Cause: The specified field does not exist on the object.
Fix: Check the field name against the object schema. Field names are snake_case.
Retry: no_retry

ENDPOINT_NOT_FOUND

Cause: The API endpoint path does not match any registered route.
Fix: Verify the URL path and HTTP method. Check the API discovery endpoint for available routes.
Retry: no_retry

Conflict Errors (409)

RESOURCE_CONFLICT

Cause: The operation conflicts with the current state of the resource.
Fix: Fetch the latest resource state and retry the operation.
Retry: retry_immediate

CONCURRENT_MODIFICATION

Cause: The record was modified by another user/process since you last read it (optimistic locking failure).
Fix: Re-fetch the record, merge changes, and retry.
Retry: retry_immediate

DELETE_RESTRICTED

Cause: The record cannot be deleted because other records depend on it (referential integrity).
Fix: Delete or reassign dependent records first, then retry the delete.
Retry: no_retry

UNIQUE_VIOLATION

Cause: A record with the same unique key already exists.
Fix: Update the existing record instead, or use a different unique key value.
Retry: no_retry

The engine throws DuplicateRecordError, whose in-process code is DUPLICATE_RECORD; the REST door translates that envelope at the boundary, so every route answers the wire code UNIQUE_VIOLATION and the in-process spelling never crosses HTTP.

LOCK_CONFLICT

Cause: The record is locked by another process or user.
Fix: Wait for the lock to be released, or contact the lock holder.
Retry: retry_backoff

Request Errors (405/428)

Added in #3842 so standardErrorCodeForHttpStatus can name every status the runtime actually returns. Without them a 405 would fall into the generic 4xx bucket and be reported as a validation failure.

METHOD_NOT_ALLOWED

Cause: The route exists but does not serve this HTTP method.
Fix: Use the method named in the response's Allow header.
Retry: no_retry

PRECONDITION_REQUIRED

Cause: The request is missing a precondition the route requires — most often an environment scope (no X-Environment-Id header and no hostname mapping).
Fix: Send the missing header, or address the environment-scoped URL form.
Retry: no_retry

Size Limit Errors (413)

PAYLOAD_TOO_LARGE is an error-code ledger code, listed under each package that answers it — @objectstack/rest and @objectstack/service-storage — not a standard-catalog member, so its status is published here rather than inherited from a category. The standard catalog names no 413 member.

PAYLOAD_TOO_LARGE

HTTP Status: 413
Cause: The request carries more than its door accepts:

• An upload over the File Storage settings' max_upload_mb. The presigned-upload door (the declared size), the chunked-upload start (the declared totalSize), the local adapter's raw upload (the body) and the chunk door (the bytes the upload already holds plus the chunk) refuse it before anything is stored. The message names the size, the limit and the setting.
• An import over its route's row ceiling — 5,000 rows on the synchronous route, 50,000 on the job route (size limits).

Fix: Raise the setting or send a smaller file; split the import across requests. Resending the same request cannot succeed.
Retry: no_retry

Rate Limit Errors (429)

RATE_LIMIT_EXCEEDED

Cause: Too many requests in the current time window.
Fix: Reduce request frequency. Check the retryAfterSeconds field for the wait.
Retry: retry_after

QUOTA_EXCEEDED

Cause: The API usage quota for the current period has been exhausted.
Fix: Wait for the quota to reset (check retryAfterSeconds), or upgrade the plan.
Retry: retry_after

Server Errors (5xx)

The heading is 5xx, not 500, because these five codes are not all served with the same status: TIMEOUT is the code a 504 carries and NOT_IMPLEMENTED the code a 501 carries (HttpStatusErrorCodeMap, packages/spec/src/api/errors.zod.ts), and SERVICE_UNAVAILABLE is a 503. The per-code status is in the quick reference at the end of this page, and pnpm check:error-status-conformance reconciles every row there against what the runtime can actually emit.

INTERNAL_ERROR

Cause: An unexpected server-side error occurred.
Fix: Report the issue with the requestId and traceId. Retry may succeed.
Retry: retry_backoff

DATABASE_ERROR

Cause: A database operation failed (connection, query, constraint).
Fix: Report the issue. May be transient — retry with backoff.
Retry: retry_backoff

TIMEOUT

Cause: The operation exceeded the maximum allowed time.
Fix: Simplify the query/operation. For large datasets, use pagination or async processing.
Retry: retry_backoff

SERVICE_UNAVAILABLE

Cause: A required internal service is temporarily unavailable.
Fix: Retry after a brief delay. Check system status.
Retry: retry_backoff

NOT_IMPLEMENTED

Cause: The requested feature or endpoint is not yet implemented.
Fix: Check the documentation for alternative approaches, or wait for the feature release.
Retry: no_retry

External Service Errors (502)

EXTERNAL_SERVICE_ERROR

Cause: An external API or service returned an error.
Fix: Check the external service status. The details field may contain the upstream error.
Retry: retry_backoff

INTEGRATION_ERROR

Cause: An integration connector encountered an error.
Fix: Verify the integration configuration and credentials.
Retry: retry_backoff

WEBHOOK_DELIVERY_FAILED

Cause: A webhook delivery attempt failed (target unreachable or returned error).
Fix: Verify the webhook URL is accessible. The system will auto-retry per delivery policy.
Retry: retry_backoff

Action Errors (/api/v1/actions)

Since #3962 /actions failures speak HTTP like every other route — the status code is the failure signal, and on success data is the handler's return value directly (single wrap).

A rejection and a crash are told apart by the thrown error: a plain throw new Error(msg), a sandboxed body's deliberate throw, or a ValidationError is a rejection (400); a TypeError / ReferenceError / a driver's own error class is a crash (500). An error carrying its own status is served with it. A validation rejection carries error.code: 'VALIDATION_FAILED' with the per-field list in error.details.fields[] — the same code and field entries /data reports (the envelope assembly promotes a thrown error's code into error.code; details is context only).

const res = await fetch(`/api/v1/actions/${object}/${action}`, { /* … */ });
const json = await res.json();
if (!res.ok) showToast(json.error?.message);  // the status IS the failure signal
else use(json.data);                          // the handler's return value

client.actions.invoke() folds this (and the pre-#3962 legacy 200 envelope) into one { success, data?, error? } result and never throws.

const res = await client.actions.invoke(object, action, { recordId, params });
if (!res.success) showToast(res.error);

Metadata API Errors (/meta)

/meta refusals carry codes registered to @objectstack/metadata-protocol in the error-code ledger, not the standard catalog above — so their status is published here rather than inherited from a category. This section documents the two type-boundary refusals the /meta request boundary raises: the type-spelling refusal, and the unmintable-type refusal that guards writes. Both answer INVALID_REQUEST with 400, so the code and the status cannot tell them apart — only the message can. It is not a complete inventory of /meta errors.

INVALID_REQUEST — unrecognised type spelling

HTTP Status: 400
Cause: The type segment of a /meta path is not a spelling ObjectStack recognises, and it evidently reaches for a metadata type the platform itself declares — a misspelling of a real type. GET /meta/viewes is refused because viewes is not a recognised spelling of the declared type view.

Fix: Address the type by its canonical singular name, or by its canonical REST plural. The refusal names both, so the correction never has to be guessed — for viewes it names view and views. See the Metadata API.
Retry: no_retry — the spelling is refused deterministically; retrying it unchanged returns the same 400.

GET /api/v1/meta/viewes answers 400 with:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "'viewes' is not a recognised spelling of metadata type 'view'. Address it as 'view' or 'views'. Refused rather than treated as a plugin-registered type, because forwarding an unrecognised spelling of a declared type would create a second namespace under type='viewes'.",
    "httpStatus": 400
  }
}

Why it is refused rather than passed through. A type segment the platform does not recognise would otherwise be treated as a plugin-registered kind, and a write under it would mint a second metadata namespace keyed by the misspelling — type='viewes' alongside type='view' — which nothing reads and nothing serves. Refusing at the boundary is what keeps one type to one key.

⛔ Not this error: a segment that reaches for no declared type — /meta/fieldz, or a plugin-registered kind such as theme — is not a misspelling of anything the platform declares, so this rule stays silent. On a read the request continues down the plugin path; on a write it meets the separate unmintable-type refusal documented immediately below, which carries the same INVALID_REQUEST code and 400 status and differs only in its message. Tell the two apart by the message, not the code.

INVALID_REQUEST — unmintable metadata type

HTTP Status: 400
Cause: A write addresses a :type segment that is not a metadata type at all — not a misspelling of a declared type, but a name the platform has no type for. PUT /meta/fieldz/showcase_task.title is refused because nothing declares fieldz, and since additionalTypes was retired a plugin cannot declare one either — so the write would mint a sys_metadata namespace under type='fieldz' that nothing reads and nothing serves.

Fix: Address a real metadata type; GET /api/v1/meta/types lists the ones the deployment carries. Unlike the spelling refusal above, this message names no replacement — the segment reaches for no declared type, so there is nothing to suggest. See the Metadata API.
Retry: no_retry — replaying the same request against the same deployment returns the same 400. ⚠️ That is stability, not determinism: the verdict is not a pure function of the type segment, and the exemption below decides whether it fires at all.

PUT /api/v1/meta/fieldz/showcase_task.title answers 400 with:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "'fieldz' is not a metadata type. The platform declares no such type, and since #8586 retired 'additionalTypes' a plugin cannot declare one either — so this write would mint a sys_metadata namespace under type='fieldz' that nothing reads and nothing serves. Address a real metadata type; GET /api/v1/meta/types lists the ones this deployment carries.",
    "httpStatus": 400
  }
}

It is write-scoped. The verdict runs on the one entry point that mints a namespace and nowhere else. Reads of an unrecognised type still answer — the live type set legitimately holds keys the static contract does not, and refusing reads would answer 400 for types this same service advertises through GET /meta/types. Rows already stored under an unrecognised type stay deletable for the opposite reason: refusing to delete them would strand the accumulation permanently instead of letting an operator clear it.

Why it is refused rather than passed through. A namespace nothing reads and nothing serves is not a harmless extra key — it accumulates silently, and every row in it is invisible to the tooling that lists, validates and ships metadata. Refusing at the mint door is what stops the first row from being written; the exemption above is what keeps that refusal from stranding the rows written before it existed.

⛔ Not this error: a segment that misspells a type the platform declares — /meta/viewes for view — is the spelling refusal documented above, which can name the replacement. And if the namespace probe fails for any reason other than sys_metadata not being provisioned yet, the request answers 503 rather than this 400: a deployment whose metadata store is unreachable is not told its type does not exist. An unprovisioned store is the one read failure that does not escalate — it counts as "no rows", and this 400 stands.

Error Response Structure

Every error response follows the EnhancedApiError schema:

interface EnhancedApiError {
  code: StandardErrorCode;       // Machine-readable error code
  message: string;               // Human-readable description
  refusal?: true;                // Producer-declared refusal: keeps message on a 5xx
  category?: ErrorCategory;      // Error category
  httpStatus?: number;           // HTTP status code
  retryable: boolean;            // Whether retry may succeed
  retryStrategy?: RetryStrategy; // Recommended retry approach
  retryAfterSeconds?: number;    // Wait before retrying (for rate limits)
  details?: unknown;             // Additional error context
  fields?: FieldError[];         // One entry per offending value
  timestamp?: string;            // ISO 8601 timestamp
  requestId?: string;            // Request tracking ID
  traceId?: string;              // Distributed trace ID
  documentation?: string;        // URL to error documentation
  helpText?: string;             // Suggested resolution actions
}

Field Error Structure

interface FieldError {
  field: string;            // Field path (supports dot notation)
  code: FieldErrorCode;     // Which CONSTRAINT the value violated — a closed,
                            // lowercase catalog, separate from error.code (ADR-0114)
  message: string;          // Human-readable error for this field
  value?: unknown;          // The invalid value (if safe to include)
  constraint?: unknown;     // The constraint that was violated (e.g., max length)
}

Field-level codes

FieldError.code is its own closed vocabulary, and it is lowercase where error.code is SCREAMING. That is deliberate (ADR-0114): a top-level code names the condition the request hit, while a field-level code names the constraint the value violated — and constraints are declared in the metadata's own snake_case, so the code and the schema property are the same word.

{ required: true }   → code 'required'
{ max_length: 50 }   → code 'max_length'
{ min_value: 0 }     → code 'min_value'

Branch on code to decide how to mark an input; show message to the user. Routes that parse with Zod map its issue codes into this catalog rather than passing them through, so fields[] speaks one vocabulary whichever route served it.

Client-Side Error Handling

TypeScript Example

import type { EnhancedApiError, FieldError } from '@objectstack/spec/api';

// The two names converged in ADR-0114 D4: the spec type and the client both say
// `fields`, so no widening cast is needed any more.
type ThrownApiError = EnhancedApiError;

async function handleApiCall() {
  try {
    const result = await client.data.create('task', { title: 'New Task' });
    return result;
  } catch (error) {
    const apiError = error as ThrownApiError;

    switch (apiError.category) {
      case 'validation':
        // Show field-level errors to the user. One entry per offending value.
        apiError.fields?.forEach(fe => {
          showFieldError(fe.field, fe.message);
        });
        break;

      case 'authentication':
        // Redirect to login
        if (apiError.code === 'EXPIRED_TOKEN') {
          await refreshToken();
          return handleApiCall(); // Retry
        }
        redirectToLogin();
        break;

      case 'rate_limit':
        // Wait and retry
        const waitTime = apiError.retryAfterSeconds ?? 60;
        await sleep(waitTime * 1000);
        return handleApiCall();

      case 'server':
      case 'external':
        // Log and retry with backoff
        console.error(`Server error [${apiError.requestId}]:`, apiError.message);
        break;

      default:
        showGenericError(apiError.message);
    }
  }
}

HTTP Status Quick Reference