Skip to content

errors.mdx

Latest commit

 

History

History
183 lines (137 loc) · 7.19 KB

errors.mdx

File metadata and controls

183 lines (137 loc) · 7.19 KB
Raw
title Errors
description Errors protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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

// Validate data
const result = EnhancedApiError.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' | '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' | 'METHOD_NOT_ALLOWED' | 'PRECONDITION_REQUIRED' | '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
message string ✅ Human-readable error message
category Enum<'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | 'rate_limit' | 'server' | 'external' | 'maintenance'> optional Error category
httpStatus number optional HTTP status code
retryable boolean ✅ Whether the request can be retried
retryStrategy Enum<'no_retry' | 'retry_immediate' | 'retry_backoff' | 'retry_after'> optional Recommended retry strategy
retryAfter number optional Seconds to wait before retrying
details any optional Additional error context
fieldErrors { field: string; code: string; message: string; value?: any; … }[] optional Field-specific validation errors
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

ErrorCategory

Allowed Values

  • validation
  • authentication
  • authorization
  • not_found
  • conflict
  • rate_limit
  • server
  • external
  • maintenance

ErrorResponse

Properties

Property Type Required Description
success 'false' ✅ Always false for error responses
error { code: Enum<'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' | 'METHOD_NOT_ALLOWED' | 'PRECONDITION_REQUIRED' | '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'>; message: string; category?: Enum<'validation' | 'authentication' | 'authorization' | 'not_found' | 'conflict' | 'rate_limit' | 'server' | 'external' | 'maintenance'>; httpStatus?: number; … } ✅ Error details
meta { timestamp?: string; requestId?: string; traceId?: string } optional Response metadata

FieldError

Properties

Property Type Required Description
field string ✅ Field path (supports dot notation)
code string ✅ Error code for this field (field-level vocabulary — see #3977)
message string ✅ Human-readable error message
value any optional The invalid value that was provided
constraint any optional The constraint that was violated (e.g., max length)

RetryStrategy

Allowed Values

  • no_retry
  • retry_immediate
  • retry_backoff
  • retry_after

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
  • METHOD_NOT_ALLOWED
  • PRECONDITION_REQUIRED
  • 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