ObjectStackErrors schema — API Protocol reference
Provides consistent, machine-readable error codes across the platform.
Standardized Error Codes Protocol
Implements P0 requirement for ObjectStack kernel. Provides consistent, machine-readable error codes across the platform.
Features:
- Categorized error codes (validation, authentication, authorization, etc.)
- HTTP status code mapping
- Localization support
- Retry guidance
Industry alignment: Google Cloud Errors, AWS Error Codes, Stripe API Errors
Source: packages/spec/src/api/errors.zod.ts
TypeScript Usage
import { EnhancedApiErrorSchema, ErrorCategory, ErrorResponseSchema, FieldErrorSchema, FieldErrorCode, RetryStrategy, StandardErrorCode } from '@objectstack/spec/api';
import type { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, FieldErrorCode, RetryStrategy, StandardErrorCode } from '@objectstack/spec/api';
// Validate data
const result = EnhancedApiErrorSchema.parse(data);EnhancedApiError
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | 'INVALID_FORMAT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_SHORT' | 'VALUE_OUT_OF_RANGE' | … +42 more> | ✅ | Machine-readable error code |
| message | string | ✅ | Human-readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim — see ApiErrorSchema.userMessage. Present only when the producer opted in at throw time; unmarked errors keep the generic consumer substitution. |
| refusal | true | optional | Producer-declared deliberate refusal — see ApiErrorSchema.refusal. Present only when the producer declared it at throw time; a declared 5xx without it is a fault whose message is withheld. Until the withhold arms read the declaration, a declared refusal is still withheld. |
| category | Enum<'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | 'rate_limit' | 'server' | 'external' | 'maintenance'> | optional | Error category |
| httpStatus | number | optional | HTTP status code |
| retryable | boolean | optional (default: false) | Whether the request can be retried |
| retryStrategy | Enum<'no_retry' | 'retry_immediate' | 'retry_backoff' | 'retry_after'> | optional | Recommended retry strategy |
| retryAfterSeconds | number | optional | Seconds to wait before retrying |
| retryAfter | never | optional | [REMOVED] EnhancedApiError.retryAfter was renamed to retryAfterSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to retryAfterSeconds; the value (seconds) is unchanged. This is the ADR-0112 error envelope, not the HTTP Retry-After response header — that header keeps its RFC 9110 name and is untouched. |
| details | any | optional | Additional error context |
| fields | { field: string; code: Enum<'required' | 'invalid_type' | 'invalid_shape' | 'unknown_field' | …>; message: string; label?: string; … }[] | optional | One entry per offending value |
| fieldErrors | never | optional | [REMOVED] EnhancedApiError.fieldErrors was renamed to fields in @objectstack/spec 17 (ADR-0114 D4) — the array is unchanged, only the property name. Every producer already emitted fields; fieldErrors was declared and never emitted, so a reader keying on it was reading a field no server sent. |
| timestamp | string | optional | When the error occurred |
| requestId | string | optional | Request ID for tracking |
| traceId | string | optional | Distributed trace ID |
| documentation | string | optional | URL to error documentation |
| helpText | string | optional | Suggested actions to resolve the error |
Allowed Values: EnhancedApiError.code
VALIDATION_ERRORINVALID_FIELDMISSING_REQUIRED_FIELDINVALID_FORMATVALUE_TOO_LONGVALUE_TOO_SHORTVALUE_OUT_OF_RANGEINVALID_REFERENCEDUPLICATE_VALUEINVALID_QUERYINVALID_FILTERINVALID_SORTMAX_RECORDS_EXCEEDEDUNAUTHENTICATEDINVALID_CREDENTIALSEXPIRED_TOKENINVALID_TOKENSESSION_EXPIREDMFA_REQUIREDEMAIL_NOT_VERIFIEDPERMISSION_DENIEDINSUFFICIENT_PRIVILEGESFIELD_NOT_ACCESSIBLERECORD_NOT_ACCESSIBLELICENSE_REQUIREDIP_RESTRICTEDTIME_RESTRICTEDRESOURCE_NOT_FOUNDOBJECT_NOT_FOUNDRECORD_NOT_FOUNDFIELD_NOT_FOUNDENDPOINT_NOT_FOUNDRESOURCE_CONFLICTCONCURRENT_MODIFICATIONDELETE_RESTRICTEDDUPLICATE_RECORDLOCK_CONFLICTMETHOD_NOT_ALLOWEDPRECONDITION_REQUIREDRATE_LIMIT_EXCEEDEDQUOTA_EXCEEDEDINTERNAL_ERRORDATABASE_ERRORTIMEOUTSERVICE_UNAVAILABLENOT_IMPLEMENTEDEXTERNAL_SERVICE_ERRORINTEGRATION_ERRORWEBHOOK_DELIVERY_FAILED
Nested Shape: EnhancedApiError.fields[number]
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | Field path (supports dot notation) |
| code | Enum<'required' | 'invalid_type' | 'invalid_shape' | 'unknown_field' | …> | ✅ | Which constraint the value violated (field-level catalog, ADR-0114) |
| message | string | ✅ | Human-readable error message, rendered in the caller’s locale |
| label | string | optional | Field display label in the caller’s locale |
| value | any | optional | The invalid value that was provided |
| constraint | Record<string, any> | optional | The constraint that was violated, as discrete values (e.g. { maxLength: 512, actual: 3000 }) |
ErrorCategory
Allowed Values
validationauthenticationauthorizationnot_foundconflictrate_limitserverexternalmaintenance
ErrorResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | false | ✅ | Always false for error responses |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; message: string; userMessage?: string; refusal?: true; … } | ✅ | Error details |
| meta | { timestamp?: string; requestId?: string; traceId?: string } | optional | Response metadata |
Nested Shape: ErrorResponse.error
| Property | Type | Required | Description |
|---|---|---|---|
| code | Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> | ✅ | Machine-readable error code |
| message | string | ✅ | Human-readable error message |
| userMessage | string | optional | Producer-marked user-facing refusal text, verbatim — see ApiErrorSchema.userMessage. Present only when the producer opted in at throw time; unmarked errors keep the generic consumer substitution. |
| refusal | true | optional | Producer-declared deliberate refusal — see ApiErrorSchema.refusal. Present only when the producer declared it at throw time; a declared 5xx without it is a fault whose message is withheld. Until the withhold arms read the declaration, a declared refusal is still withheld. |
| category | Enum<'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | …> | optional | Error category |
| httpStatus | number | optional | HTTP status code |
| retryable | boolean | optional (default: false) | Whether the request can be retried |
| retryStrategy | Enum<'no_retry' | 'retry_immediate' | 'retry_backoff' | 'retry_after'> | optional | Recommended retry strategy |
| retryAfterSeconds | number | optional | Seconds to wait before retrying |
| retryAfter | never | optional | [REMOVED] EnhancedApiError.retryAfter was renamed to retryAfterSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to retryAfterSeconds; the value (seconds) is unchanged. This is the ADR-0112 error envelope, not the HTTP Retry-After response header — that header keeps its RFC 9110 name and is untouched. |
| details | any | optional | Additional error context |
| fields | { field: string; code: Enum<'required' | 'invalid_type' | 'invalid_shape' | 'unknown_field' | …>; message: string; label?: string; … }[] | optional | One entry per offending value |
| fieldErrors | never | optional | [REMOVED] EnhancedApiError.fieldErrors was renamed to fields in @objectstack/spec 17 (ADR-0114 D4) — the array is unchanged, only the property name. Every producer already emitted fields; fieldErrors was declared and never emitted, so a reader keying on it was reading a field no server sent. |
| timestamp | string | optional | When the error occurred |
| requestId | string | optional | Request ID for tracking |
| traceId | string | optional | Distributed trace ID |
| documentation | string | optional | URL to error documentation |
| helpText | string | optional | Suggested actions to resolve the error |
FieldError
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | Field path (supports dot notation) |
| code | Enum<'required' | 'invalid_type' | 'invalid_shape' | 'unknown_field' | 'invalid_boolean' | 'invalid_number' | 'invalid_date' | 'invalid_time' | 'invalid_email' | … +21 more> | ✅ | Which constraint the value violated (field-level catalog, ADR-0114) |
| message | string | ✅ | Human-readable error message, rendered in the caller’s locale |
| label | string | optional | Field display label in the caller’s locale |
| value | any | optional | The invalid value that was provided |
| constraint | Record<string, any> | optional | The constraint that was violated, as discrete values (e.g. { maxLength: 512, actual: 3000 }) |
Allowed Values: FieldError.code
requiredinvalid_typeinvalid_shapeunknown_fieldinvalid_booleaninvalid_numberinvalid_dateinvalid_timeinvalid_emailinvalid_urlinvalid_phoneinvalid_jsoninvalid_formatmin_lengthmax_lengthmin_valuemax_valuemax_scalemax_precisionmin_itemsmax_itemsinvalid_optionvalue_domaininvalid_valuereference_not_foundreference_ambiguousrule_violationjson_schema_violationinvalid_initial_stateinvalid_transition
FieldErrorCode
Allowed Values
requiredinvalid_typeinvalid_shapeunknown_fieldinvalid_booleaninvalid_numberinvalid_dateinvalid_timeinvalid_emailinvalid_urlinvalid_phoneinvalid_jsoninvalid_formatmin_lengthmax_lengthmin_valuemax_valuemax_scalemax_precisionmin_itemsmax_itemsinvalid_optionvalue_domaininvalid_valuereference_not_foundreference_ambiguousrule_violationjson_schema_violationinvalid_initial_stateinvalid_transition
RetryStrategy
Allowed Values
no_retryretry_immediateretry_backoffretry_after
StandardErrorCode
Allowed Values
VALIDATION_ERRORINVALID_FIELDMISSING_REQUIRED_FIELDINVALID_FORMATVALUE_TOO_LONGVALUE_TOO_SHORTVALUE_OUT_OF_RANGEINVALID_REFERENCEDUPLICATE_VALUEINVALID_QUERYINVALID_FILTERINVALID_SORTMAX_RECORDS_EXCEEDEDUNAUTHENTICATEDINVALID_CREDENTIALSEXPIRED_TOKENINVALID_TOKENSESSION_EXPIREDMFA_REQUIREDEMAIL_NOT_VERIFIEDPERMISSION_DENIEDINSUFFICIENT_PRIVILEGESFIELD_NOT_ACCESSIBLERECORD_NOT_ACCESSIBLELICENSE_REQUIREDIP_RESTRICTEDTIME_RESTRICTEDRESOURCE_NOT_FOUNDOBJECT_NOT_FOUNDRECORD_NOT_FOUNDFIELD_NOT_FOUNDENDPOINT_NOT_FOUNDRESOURCE_CONFLICTCONCURRENT_MODIFICATIONDELETE_RESTRICTEDDUPLICATE_RECORDLOCK_CONFLICTMETHOD_NOT_ALLOWEDPRECONDITION_REQUIREDRATE_LIMIT_EXCEEDEDQUOTA_EXCEEDEDINTERNAL_ERRORDATABASE_ERRORTIMEOUTSERVICE_UNAVAILABLENOT_IMPLEMENTEDEXTERNAL_SERVICE_ERRORINTEGRATION_ERRORWEBHOOK_DELIVERY_FAILED
Endpoint
Endpoint schemas of the ObjectStack API Protocol: ApiEndpoint, ApiMapping — each property with its type, default and a TypeScript example.
Protocol
Protocol schemas of the ObjectStack API Protocol: AiAgentCapabilities and 136 more — each property with its type, default and a TypeScript example.