/** * @vorionsys/shared-constants - Error Codes * * Standardized error codes across all Vorion ecosystem APIs * Ensures consistent error handling and reporting * * @see https://cognigate.dev/docs/errors */ export declare enum ErrorCategory { /** Authentication and authorization errors (4xx) */ AUTH = "auth", /** Validation and input errors (4xx) */ VALIDATION = "validation", /** Rate limiting and quota errors (429) */ RATE_LIMIT = "rate_limit", /** Resource not found errors (404) */ NOT_FOUND = "not_found", /** Trust and governance errors (4xx) */ TRUST = "trust", /** Server and internal errors (5xx) */ SERVER = "server", /** External service errors (5xx) */ EXTERNAL = "external", /** Configuration errors */ CONFIG = "config" } export interface ErrorDefinition { /** Unique error code */ code: string; /** HTTP status code */ httpStatus: number; /** Error category */ category: ErrorCategory; /** Human-readable message template */ message: string; /** Whether this error is retryable */ retryable: boolean; /** Documentation URL for this error */ docsUrl?: string; } export declare const AUTH_ERRORS: { readonly MISSING_API_KEY: { readonly code: "E1001"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "API key is missing. Include it in the Authorization header."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/authentication"; }; readonly INVALID_API_KEY: { readonly code: "E1002"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "API key is invalid or has been revoked."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/authentication"; }; readonly EXPIRED_API_KEY: { readonly code: "E1003"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "API key has expired. Generate a new key."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/authentication"; }; readonly INSUFFICIENT_PERMISSIONS: { readonly code: "E1004"; readonly httpStatus: 403; readonly category: ErrorCategory.AUTH; readonly message: "Insufficient permissions for this operation."; readonly retryable: false; }; readonly AGENT_NOT_AUTHORIZED: { readonly code: "E1005"; readonly httpStatus: 403; readonly category: ErrorCategory.AUTH; readonly message: "Agent is not authorized for this action."; readonly retryable: false; }; readonly TOKEN_EXPIRED: { readonly code: "E1006"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "Authentication token has expired."; readonly retryable: false; }; readonly MFA_REQUIRED: { readonly code: "E1007"; readonly httpStatus: 403; readonly category: ErrorCategory.AUTH; readonly message: "Multi-factor authentication is required for this operation."; readonly retryable: false; }; }; export declare const VALIDATION_ERRORS: { readonly INVALID_REQUEST: { readonly code: "E2001"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Request body is invalid or malformed."; readonly retryable: false; }; readonly MISSING_REQUIRED_FIELD: { readonly code: "E2002"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Required field is missing: {field}"; readonly retryable: false; }; readonly INVALID_FIELD_TYPE: { readonly code: "E2003"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Field {field} has invalid type. Expected {expected}."; readonly retryable: false; }; readonly INVALID_FIELD_VALUE: { readonly code: "E2004"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Field {field} has invalid value."; readonly retryable: false; }; readonly PAYLOAD_TOO_LARGE: { readonly code: "E2005"; readonly httpStatus: 413; readonly category: ErrorCategory.VALIDATION; readonly message: "Request payload exceeds maximum size of {maxSize}."; readonly retryable: false; }; readonly INVALID_JSON: { readonly code: "E2006"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Request body is not valid JSON."; readonly retryable: false; }; readonly INVALID_CAR_ID: { readonly code: "E2007"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Invalid CAR ID format. Expected: car:domain/category/name:version"; readonly retryable: false; readonly docsUrl: "https://carid.vorion.org/format"; }; readonly INVALID_TRUST_SCORE: { readonly code: "E2008"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Trust score must be between 0 and 1000."; readonly retryable: false; }; }; export declare const RATE_LIMIT_ERRORS: { readonly RATE_LIMIT_EXCEEDED: { readonly code: "E3001"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Rate limit exceeded. Retry after {retryAfter} seconds."; readonly retryable: true; }; readonly QUOTA_EXCEEDED: { readonly code: "E3002"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Monthly quota exceeded. Upgrade your tier or wait for reset."; readonly retryable: false; }; readonly CONCURRENT_LIMIT: { readonly code: "E3003"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Too many concurrent requests. Max burst: {burstLimit}."; readonly retryable: true; }; readonly DAILY_LIMIT_EXCEEDED: { readonly code: "E3004"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Daily request limit exceeded. Resets at midnight UTC."; readonly retryable: true; }; }; export declare const NOT_FOUND_ERRORS: { readonly RESOURCE_NOT_FOUND: { readonly code: "E4001"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Resource not found: {resourceType}/{resourceId}"; readonly retryable: false; }; readonly AGENT_NOT_FOUND: { readonly code: "E4002"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Agent not found: {agentId}"; readonly retryable: false; }; readonly PROOF_NOT_FOUND: { readonly code: "E4003"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Proof not found: {proofId}"; readonly retryable: false; }; readonly ENDPOINT_NOT_FOUND: { readonly code: "E4004"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "API endpoint not found."; readonly retryable: false; }; readonly ATTESTATION_NOT_FOUND: { readonly code: "E4005"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Attestation not found: {attestationId}"; readonly retryable: false; }; }; export declare const TRUST_ERRORS: { readonly TRUST_TIER_INSUFFICIENT: { readonly code: "E5001"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Trust tier {currentTier} insufficient. Required: {requiredTier}."; readonly retryable: false; readonly docsUrl: "https://basis.vorion.org/tiers"; }; readonly CAPABILITY_NOT_AVAILABLE: { readonly code: "E5002"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Capability {capability} not available at tier {tier}."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/capabilities"; }; readonly GOVERNANCE_DENIED: { readonly code: "E5003"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Action denied by governance policy: {reason}."; readonly retryable: false; }; readonly AGENT_SUSPENDED: { readonly code: "E5004"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Agent is suspended. Contact support for reinstatement."; readonly retryable: false; }; readonly PROOF_VERIFICATION_FAILED: { readonly code: "E5005"; readonly httpStatus: 400; readonly category: ErrorCategory.TRUST; readonly message: "Proof verification failed: {reason}."; readonly retryable: false; }; readonly ATTESTATION_INVALID: { readonly code: "E5006"; readonly httpStatus: 400; readonly category: ErrorCategory.TRUST; readonly message: "Attestation is invalid or has expired."; readonly retryable: false; }; readonly ESCALATION_REQUIRED: { readonly code: "E5007"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Action requires human approval. Escalation ID: {escalationId}."; readonly retryable: false; }; }; export declare const SERVER_ERRORS: { readonly INTERNAL_ERROR: { readonly code: "E6001"; readonly httpStatus: 500; readonly category: ErrorCategory.SERVER; readonly message: "An internal error occurred. Please try again later."; readonly retryable: true; }; readonly SERVICE_UNAVAILABLE: { readonly code: "E6002"; readonly httpStatus: 503; readonly category: ErrorCategory.SERVER; readonly message: "Service is temporarily unavailable. Please try again later."; readonly retryable: true; }; readonly DATABASE_ERROR: { readonly code: "E6003"; readonly httpStatus: 500; readonly category: ErrorCategory.SERVER; readonly message: "Database operation failed. Please try again later."; readonly retryable: true; }; readonly MAINTENANCE_MODE: { readonly code: "E6004"; readonly httpStatus: 503; readonly category: ErrorCategory.SERVER; readonly message: "Service is under maintenance. Expected completion: {eta}."; readonly retryable: true; }; }; export declare const EXTERNAL_ERRORS: { readonly BLOCKCHAIN_ERROR: { readonly code: "E7001"; readonly httpStatus: 502; readonly category: ErrorCategory.EXTERNAL; readonly message: "Blockchain network error. Please try again later."; readonly retryable: true; }; readonly UPSTREAM_TIMEOUT: { readonly code: "E7002"; readonly httpStatus: 504; readonly category: ErrorCategory.EXTERNAL; readonly message: "Upstream service timed out."; readonly retryable: true; }; readonly EXTERNAL_SERVICE_ERROR: { readonly code: "E7003"; readonly httpStatus: 502; readonly category: ErrorCategory.EXTERNAL; readonly message: "External service error: {service}."; readonly retryable: true; }; }; export declare const ERROR_CODES: { readonly BLOCKCHAIN_ERROR: { readonly code: "E7001"; readonly httpStatus: 502; readonly category: ErrorCategory.EXTERNAL; readonly message: "Blockchain network error. Please try again later."; readonly retryable: true; }; readonly UPSTREAM_TIMEOUT: { readonly code: "E7002"; readonly httpStatus: 504; readonly category: ErrorCategory.EXTERNAL; readonly message: "Upstream service timed out."; readonly retryable: true; }; readonly EXTERNAL_SERVICE_ERROR: { readonly code: "E7003"; readonly httpStatus: 502; readonly category: ErrorCategory.EXTERNAL; readonly message: "External service error: {service}."; readonly retryable: true; }; readonly INTERNAL_ERROR: { readonly code: "E6001"; readonly httpStatus: 500; readonly category: ErrorCategory.SERVER; readonly message: "An internal error occurred. Please try again later."; readonly retryable: true; }; readonly SERVICE_UNAVAILABLE: { readonly code: "E6002"; readonly httpStatus: 503; readonly category: ErrorCategory.SERVER; readonly message: "Service is temporarily unavailable. Please try again later."; readonly retryable: true; }; readonly DATABASE_ERROR: { readonly code: "E6003"; readonly httpStatus: 500; readonly category: ErrorCategory.SERVER; readonly message: "Database operation failed. Please try again later."; readonly retryable: true; }; readonly MAINTENANCE_MODE: { readonly code: "E6004"; readonly httpStatus: 503; readonly category: ErrorCategory.SERVER; readonly message: "Service is under maintenance. Expected completion: {eta}."; readonly retryable: true; }; readonly TRUST_TIER_INSUFFICIENT: { readonly code: "E5001"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Trust tier {currentTier} insufficient. Required: {requiredTier}."; readonly retryable: false; readonly docsUrl: "https://basis.vorion.org/tiers"; }; readonly CAPABILITY_NOT_AVAILABLE: { readonly code: "E5002"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Capability {capability} not available at tier {tier}."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/capabilities"; }; readonly GOVERNANCE_DENIED: { readonly code: "E5003"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Action denied by governance policy: {reason}."; readonly retryable: false; }; readonly AGENT_SUSPENDED: { readonly code: "E5004"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Agent is suspended. Contact support for reinstatement."; readonly retryable: false; }; readonly PROOF_VERIFICATION_FAILED: { readonly code: "E5005"; readonly httpStatus: 400; readonly category: ErrorCategory.TRUST; readonly message: "Proof verification failed: {reason}."; readonly retryable: false; }; readonly ATTESTATION_INVALID: { readonly code: "E5006"; readonly httpStatus: 400; readonly category: ErrorCategory.TRUST; readonly message: "Attestation is invalid or has expired."; readonly retryable: false; }; readonly ESCALATION_REQUIRED: { readonly code: "E5007"; readonly httpStatus: 403; readonly category: ErrorCategory.TRUST; readonly message: "Action requires human approval. Escalation ID: {escalationId}."; readonly retryable: false; }; readonly RESOURCE_NOT_FOUND: { readonly code: "E4001"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Resource not found: {resourceType}/{resourceId}"; readonly retryable: false; }; readonly AGENT_NOT_FOUND: { readonly code: "E4002"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Agent not found: {agentId}"; readonly retryable: false; }; readonly PROOF_NOT_FOUND: { readonly code: "E4003"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Proof not found: {proofId}"; readonly retryable: false; }; readonly ENDPOINT_NOT_FOUND: { readonly code: "E4004"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "API endpoint not found."; readonly retryable: false; }; readonly ATTESTATION_NOT_FOUND: { readonly code: "E4005"; readonly httpStatus: 404; readonly category: ErrorCategory.NOT_FOUND; readonly message: "Attestation not found: {attestationId}"; readonly retryable: false; }; readonly RATE_LIMIT_EXCEEDED: { readonly code: "E3001"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Rate limit exceeded. Retry after {retryAfter} seconds."; readonly retryable: true; }; readonly QUOTA_EXCEEDED: { readonly code: "E3002"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Monthly quota exceeded. Upgrade your tier or wait for reset."; readonly retryable: false; }; readonly CONCURRENT_LIMIT: { readonly code: "E3003"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Too many concurrent requests. Max burst: {burstLimit}."; readonly retryable: true; }; readonly DAILY_LIMIT_EXCEEDED: { readonly code: "E3004"; readonly httpStatus: 429; readonly category: ErrorCategory.RATE_LIMIT; readonly message: "Daily request limit exceeded. Resets at midnight UTC."; readonly retryable: true; }; readonly INVALID_REQUEST: { readonly code: "E2001"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Request body is invalid or malformed."; readonly retryable: false; }; readonly MISSING_REQUIRED_FIELD: { readonly code: "E2002"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Required field is missing: {field}"; readonly retryable: false; }; readonly INVALID_FIELD_TYPE: { readonly code: "E2003"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Field {field} has invalid type. Expected {expected}."; readonly retryable: false; }; readonly INVALID_FIELD_VALUE: { readonly code: "E2004"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Field {field} has invalid value."; readonly retryable: false; }; readonly PAYLOAD_TOO_LARGE: { readonly code: "E2005"; readonly httpStatus: 413; readonly category: ErrorCategory.VALIDATION; readonly message: "Request payload exceeds maximum size of {maxSize}."; readonly retryable: false; }; readonly INVALID_JSON: { readonly code: "E2006"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Request body is not valid JSON."; readonly retryable: false; }; readonly INVALID_CAR_ID: { readonly code: "E2007"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Invalid CAR ID format. Expected: car:domain/category/name:version"; readonly retryable: false; readonly docsUrl: "https://carid.vorion.org/format"; }; readonly INVALID_TRUST_SCORE: { readonly code: "E2008"; readonly httpStatus: 400; readonly category: ErrorCategory.VALIDATION; readonly message: "Trust score must be between 0 and 1000."; readonly retryable: false; }; readonly MISSING_API_KEY: { readonly code: "E1001"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "API key is missing. Include it in the Authorization header."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/authentication"; }; readonly INVALID_API_KEY: { readonly code: "E1002"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "API key is invalid or has been revoked."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/authentication"; }; readonly EXPIRED_API_KEY: { readonly code: "E1003"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "API key has expired. Generate a new key."; readonly retryable: false; readonly docsUrl: "https://cognigate.dev/docs/authentication"; }; readonly INSUFFICIENT_PERMISSIONS: { readonly code: "E1004"; readonly httpStatus: 403; readonly category: ErrorCategory.AUTH; readonly message: "Insufficient permissions for this operation."; readonly retryable: false; }; readonly AGENT_NOT_AUTHORIZED: { readonly code: "E1005"; readonly httpStatus: 403; readonly category: ErrorCategory.AUTH; readonly message: "Agent is not authorized for this action."; readonly retryable: false; }; readonly TOKEN_EXPIRED: { readonly code: "E1006"; readonly httpStatus: 401; readonly category: ErrorCategory.AUTH; readonly message: "Authentication token has expired."; readonly retryable: false; }; readonly MFA_REQUIRED: { readonly code: "E1007"; readonly httpStatus: 403; readonly category: ErrorCategory.AUTH; readonly message: "Multi-factor authentication is required for this operation."; readonly retryable: false; }; }; /** * Get error definition by code */ export declare function getErrorByCode(code: string): ErrorDefinition | undefined; /** * Get all errors by category */ export declare function getErrorsByCategory(category: ErrorCategory): ErrorDefinition[]; /** * Get all retryable errors */ export declare function getRetryableErrors(): ErrorDefinition[]; /** * Format error message with parameters */ export declare function formatErrorMessage(error: ErrorDefinition, params: Record): string; /** * Create a structured error response */ export declare function createErrorResponse(error: ErrorDefinition, params?: Record, requestId?: string): { error: { requestId?: string | undefined; docsUrl?: string | undefined; code: string; message: string; category: ErrorCategory; retryable: boolean; }; status: number; }; export type ErrorCode = keyof typeof ERROR_CODES; //# sourceMappingURL=error-codes.d.ts.map