---
title: Errors
description: Errors protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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

<Callout type="info">
**Source:** `packages/spec/src/api/errors.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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

| 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' \| '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** | `Object[]` | 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 |


---

## ErrorResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Always false for error responses |
| **error** | `Object` | ✅ | Error details |
| **meta** | `Object` | optional | Response metadata |


---

## FieldError

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field path (supports dot notation) |
| **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' \| '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 |
| **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) |


---

## 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`


---

