ObjectStackObjectStack

Errors

Errors protocol schemas

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 { EnhancedApiError, ErrorResponse, FieldError, StandardErrorCode } from '@objectstack/spec/api';
import type { EnhancedApiError, ErrorResponse, FieldError, StandardErrorCode } from '@objectstack/spec/api';

// Validate data
const result = EnhancedApiError.parse(data);

EnhancedApiError

Properties

PropertyTypeRequiredDescription
codeEnum<'validation_error' | 'invalid_field' | 'missing_required_field' | 'invalid_format' | 'value_too_long' | 'value_too_short' | 'value_out_of_range' | 'invalid_reference' | 'duplicate_value' | 'invalid_query' | 'invalid_filter' | 'invalid_sort' | 'max_records_exceeded' | 'unauthenticated' | 'invalid_credentials' | 'expired_token' | 'invalid_token' | 'session_expired' | 'mfa_required' | 'email_not_verified' | 'permission_denied' | 'insufficient_privileges' | 'field_not_accessible' | 'record_not_accessible' | 'license_required' | 'ip_restricted' | 'time_restricted' | 'resource_not_found' | 'object_not_found' | 'record_not_found' | 'field_not_found' | 'endpoint_not_found' | 'resource_conflict' | 'concurrent_modification' | 'delete_restricted' | 'duplicate_record' | 'lock_conflict' | 'rate_limit_exceeded' | 'quota_exceeded' | 'concurrent_limit_exceeded' | 'internal_error' | 'database_error' | 'timeout' | 'service_unavailable' | 'not_implemented' | 'external_service_error' | 'integration_error' | 'webhook_delivery_failed' | 'batch_partial_failure' | 'batch_complete_failure' | 'transaction_failed'>✅Machine-readable error code
messagestring✅Human-readable error message
categoryEnum<'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | 'rate_limit' | 'server' | 'external' | 'maintenance'>optionalError category
httpStatusnumberoptionalHTTP status code
retryableboolean✅Whether the request can be retried
retryStrategyEnum<'no_retry' | 'retry_immediate' | 'retry_backoff' | 'retry_after'>optionalRecommended retry strategy
retryAfternumberoptionalSeconds to wait before retrying
detailsanyoptionalAdditional error context
fieldErrorsObject[]optionalField-specific validation errors
timestampstringoptionalWhen the error occurred
requestIdstringoptionalRequest ID for tracking
traceIdstringoptionalDistributed trace ID
documentationstringoptionalURL to error documentation
helpTextstringoptionalSuggested actions to resolve the error

ErrorResponse

Properties

PropertyTypeRequiredDescription
successboolean✅Always false for error responses
errorObject✅Error details
metaObjectoptionalResponse metadata

FieldError

Properties

PropertyTypeRequiredDescription
fieldstring✅Field path (supports dot notation)
codeEnum<'validation_error' | 'invalid_field' | 'missing_required_field' | 'invalid_format' | 'value_too_long' | 'value_too_short' | 'value_out_of_range' | 'invalid_reference' | 'duplicate_value' | 'invalid_query' | 'invalid_filter' | 'invalid_sort' | 'max_records_exceeded' | 'unauthenticated' | 'invalid_credentials' | 'expired_token' | 'invalid_token' | 'session_expired' | 'mfa_required' | 'email_not_verified' | 'permission_denied' | 'insufficient_privileges' | 'field_not_accessible' | 'record_not_accessible' | 'license_required' | 'ip_restricted' | 'time_restricted' | 'resource_not_found' | 'object_not_found' | 'record_not_found' | 'field_not_found' | 'endpoint_not_found' | 'resource_conflict' | 'concurrent_modification' | 'delete_restricted' | 'duplicate_record' | 'lock_conflict' | 'rate_limit_exceeded' | 'quota_exceeded' | 'concurrent_limit_exceeded' | 'internal_error' | 'database_error' | 'timeout' | 'service_unavailable' | 'not_implemented' | 'external_service_error' | 'integration_error' | 'webhook_delivery_failed' | 'batch_partial_failure' | 'batch_complete_failure' | 'transaction_failed'>✅Error code for this field
messagestring✅Human-readable error message
valueanyoptionalThe invalid value that was provided
constraintanyoptionalThe constraint that was violated (e.g., max length)

StandardErrorCode

Allowed Values

  • validation_error
  • invalid_field
  • missing_required_field
  • invalid_format
  • value_too_long
  • value_too_short
  • value_out_of_range
  • invalid_reference
  • duplicate_value
  • invalid_query
  • invalid_filter
  • invalid_sort
  • max_records_exceeded
  • unauthenticated
  • invalid_credentials
  • expired_token
  • invalid_token
  • session_expired
  • mfa_required
  • email_not_verified
  • permission_denied
  • insufficient_privileges
  • field_not_accessible
  • record_not_accessible
  • license_required
  • ip_restricted
  • time_restricted
  • resource_not_found
  • object_not_found
  • record_not_found
  • field_not_found
  • endpoint_not_found
  • resource_conflict
  • concurrent_modification
  • delete_restricted
  • duplicate_record
  • lock_conflict
  • rate_limit_exceeded
  • quota_exceeded
  • concurrent_limit_exceeded
  • internal_error
  • database_error
  • timeout
  • service_unavailable
  • not_implemented
  • external_service_error
  • integration_error
  • webhook_delivery_failed
  • batch_partial_failure
  • batch_complete_failure
  • transaction_failed

On this page

TypeScript UsageEnhancedApiErrorPropertiesErrorResponsePropertiesFieldErrorPropertiesStandardErrorCodeAllowed Values