{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"PERS Error Handling"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"pers-error-handling","__idx":0},"children":["PERS Error Handling"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-structure","__idx":1},"children":["Error Response Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PERS API uses structured error responses for consistent error handling across all endpoints. All errors follow the same format with security-filtered messages and correlation IDs for support."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-structured-errors","__idx":2},"children":["Why Structured Errors?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Consistency:"]}," All errors follow a uniform structure and categorization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Security:"]}," Sensitive system details are filtered out; only safe messages are returned"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Traceability:"]}," Every error includes a correlation ID for support and debugging"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Programmatic Handling:"]}," Structured format enables reliable error processing"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-error-format","__idx":3},"children":["API Error Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All PERS API errors return structured JSON responses following RFC 7807 (Problem Details for HTTP APIs):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 404,\n  \"title\": \"Resource Not Found\",\n  \"detail\": \"User with ID 12345 could not be found\",\n  \"message\": \"The requested user could not be found\",\n  \"code\": \"USER_NOT_FOUND\",\n  \"category\": \"DOMAIN_RULE\",\n  \"timestamp\": \"2026-01-15T10:30:00.000Z\",\n  \"correlationId\": \"pers-abc123-def456\",\n  \"retryable\": false,\n  \"domain\": \"user\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-response-fields","__idx":4},"children":["Error Response Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable error summary"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specific error explanation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error message (usually same as detail)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error code for programmatic handling"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["category"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error classification (VALIDATION, SECURITY, etc.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO timestamp when error occurred"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request correlation ID for distributed tracing and support"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retryable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether operation can be retried"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["domain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Domain that generated the error (user, campaign, transaction, etc.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional structured error context (optional)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Target property/parameter for validation errors (optional)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"typescript-support","__idx":5},"children":["TypeScript Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For TypeScript applications, import error types from the shared library:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { StructuredError, ErrorCategory } from '@explorins/pers-shared';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-categories--http-status-mapping","__idx":6},"children":["Error Categories & HTTP Status Mapping"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Category"},"children":["Category"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retryable"},"children":["Retryable"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["VALIDATION"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid request data or format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SECURITY"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401/403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication/authorization failures"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DOMAIN_RULE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404/409/422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Business logic and resource errors"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No/Maybe"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TECHNICAL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Application/configuration issues"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maybe"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RATE_LIMIT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API rate limit exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TIMEOUT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["504"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["INFRASTRUCTURE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["503"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["External service failures"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UNKNOWN"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unclassified errors"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maybe"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-error-codes-by-domain","__idx":7},"children":["Common Error Codes by Domain"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"user-domain","__idx":8},"children":["User Domain"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User with specified ID does not exist"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ALREADY_EXISTS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User with this identifier already exists"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_NOT_AUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User lacks required permissions"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"campaign-domain","__idx":9},"children":["Campaign Domain"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAMPAIGN_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Campaign does not exist"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAMPAIGN_NOT_ACTIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Campaign is not currently active"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAMPAIGN_ALREADY_CLAIMED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User has already claimed this campaign"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAMPAIGN_CLAIM_LIMIT_REACHED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User has reached claim limit"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAMPAIGN_COOLDOWN_ACTIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Claim cooldown period is active"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAMPAIGN_CONDITION_NOT_MET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Campaign conditions not satisfied"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-domain","__idx":10},"children":["Transaction Domain"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction does not exist"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_ALREADY_COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction was already processed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_EXPIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction has expired"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSUFFICIENT_BALANCE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient token balance"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-domain","__idx":11},"children":["Authentication Domain"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHENTICATION_REQUIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Valid credentials required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZATION_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient permissions"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_TOKEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT token is invalid"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOKEN_EXPIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT token has expired"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-domain","__idx":12},"children":["Webhook Domain"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEBHOOK_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook configuration not found"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEBHOOK_INACTIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook is disabled"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEBHOOK_SOURCE_NOT_ALLOWED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller source not in allowed list"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEBHOOK_SIGNATURE_INVALID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signature verification failed"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"generic-codes","__idx":13},"children":["Generic Codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESOURCE_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generic resource not found"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESOURCE_CONFLICT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Concurrent modification detected"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Input validation failed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS_RULE_VIOLATION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Business rule constraint violated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unexpected server error"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-examples","__idx":14},"children":["Error Handling Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-error-response","__idx":15},"children":["Example Error Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication Error (401)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 401,\n  \"title\": \"Authentication Required\",\n  \"detail\": \"Valid authentication credentials are required\",\n  \"message\": \"Please log in to access this resource\",\n  \"code\": \"AUTHENTICATION_REQUIRED\",\n  \"category\": \"SECURITY\",\n  \"timestamp\": \"2026-01-15T10:30:00.000Z\",\n  \"correlationId\": \"pers-def456-ghi789\",\n  \"retryable\": false\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validation Error (400)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 400,\n  \"title\": \"Validation Error\",\n  \"detail\": \"The email field is required\",\n  \"message\": \"The email field is required\",\n  \"code\": \"VALIDATION_ERROR\",\n  \"category\": \"VALIDATION\",\n  \"timestamp\": \"2026-01-15T10:30:00.000Z\",\n  \"correlationId\": \"pers-jkl012-mno345\",\n  \"details\": {\n    \"field\": \"email\",\n    \"rejectedValue\": null\n  },\n  \"retryable\": false\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"client-side-error-handling","__idx":16},"children":["Client-Side Error Handling"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Example: Handling API errors in JavaScript/TypeScript\nasync function callAPI() {\n  try {\n    const response = await fetch('/api/users', {\n      method: 'POST',\n      headers: {\n        'Authorization': 'Bearer your-token',\n        'Content-Type': 'application/json'\n      },\n      body: JSON.stringify({ name: 'John' })\n    });\n    \n    if (!response.ok) {\n      const error = await response.json();\n      \n      // Handle different error categories\n      if (error.category === 'SECURITY') {\n        // Redirect to login\n        window.location.href = '/login';\n      } else if (error.category === 'VALIDATION') {\n        // Show validation errors to user\n        showValidationError(error.details);\n      } else {\n        // Show generic error message\n        showErrorMessage(error.message);\n      }\n      return;\n    }\n    \n    const data = await response.json();\n    // Handle success response\n  } catch (networkError) {\n    // Handle network errors\n    showErrorMessage('Network error. Please try again.');\n  }\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-error-features","__idx":17},"children":["Advanced Error Features"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"correlation-id-tracking","__idx":18},"children":["Correlation ID Tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every request and error response includes a unique correlation ID for distributed tracing:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automatically generated for each request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Included in response headers: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Correlation-ID"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persisted across service boundaries for end-to-end tracing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Essential for debugging issues across distributed systems"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"security-filtering","__idx":19},"children":["Security Filtering"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API implements intelligent message safety filtering:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["System internals (stack traces, database errors) are never exposed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sensitive data (secrets, keys, credentials) is automatically filtered"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Business-friendly error messages are preserved"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Technical errors are sanitized for user consumption"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"category-specific-error-interfaces","__idx":20},"children":["Category-Specific Error Interfaces"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For enhanced type safety in TypeScript applications:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { \n  ValidationStructuredError,\n  DomainRuleStructuredError,\n  SecurityStructuredError,\n  RateLimitStructuredError\n} from '@explorins/pers-shared';\n\n// Validation errors include field violations\ninterface ValidationStructuredError {\n  category: 'VALIDATION';\n  details: {\n    violations: Array<{\n      field: string;\n      code: string;\n      message: string;\n      rejectedValue?: any;\n    }>;\n  };\n  target: string; // Required field\n  retryable: false;\n}\n\n// Rate limit errors include quota information\ninterface RateLimitStructuredError {\n  category: 'RATE_LIMIT';\n  details: {\n    limit: number;\n    remaining: number;\n    resetTime: string; // ISO 8601\n    window: string; // e.g., \"1h\", \"1d\"\n  };\n  retryable: true;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-headers","__idx":21},"children":["Response Headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Error responses include correlation tracking headers:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Correlation-ID"]},": Unique request identifier (set for all responses)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Response-Time"]},": ISO timestamp of response generation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Access-Control-Expose-Headers"]},": Exposes correlation ID for CORS requests"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": Additional error metadata (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["category"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retryable"]},", etc.) is available in the response body, not as separate headers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-features","__idx":22},"children":["Security Features"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["System error details are never exposed to API consumers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sensitive data automatically filtered using pattern matching"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Every error includes a correlation ID for traceability"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All errors are logged with full context for debugging"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Consistent error categorization across all domains"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Message safety filtering prevents information leakage"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For further details, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/5.authentication-guide"},"children":["Authentication Guide"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/6.developer-resources"},"children":["Developer Resources"]},"."]}]},"headings":[{"value":"PERS Error Handling","id":"pers-error-handling","depth":1},{"value":"Error Response Structure","id":"error-response-structure","depth":2},{"value":"Why Structured Errors?","id":"why-structured-errors","depth":3},{"value":"API Error Format","id":"api-error-format","depth":2},{"value":"Error Response Fields","id":"error-response-fields","depth":3},{"value":"TypeScript Support","id":"typescript-support","depth":3},{"value":"Error Categories & HTTP Status Mapping","id":"error-categories--http-status-mapping","depth":2},{"value":"Common Error Codes by Domain","id":"common-error-codes-by-domain","depth":2},{"value":"User Domain","id":"user-domain","depth":3},{"value":"Campaign Domain","id":"campaign-domain","depth":3},{"value":"Transaction Domain","id":"transaction-domain","depth":3},{"value":"Authentication Domain","id":"authentication-domain","depth":3},{"value":"Webhook Domain","id":"webhook-domain","depth":3},{"value":"Generic Codes","id":"generic-codes","depth":3},{"value":"Error Handling Examples","id":"error-handling-examples","depth":2},{"value":"Example Error Response","id":"example-error-response","depth":3},{"value":"Client-Side Error Handling","id":"client-side-error-handling","depth":3},{"value":"Advanced Error Features","id":"advanced-error-features","depth":2},{"value":"Correlation ID Tracking","id":"correlation-id-tracking","depth":3},{"value":"Security Filtering","id":"security-filtering","depth":3},{"value":"Category-Specific Error Interfaces","id":"category-specific-error-interfaces","depth":3},{"value":"Response Headers","id":"response-headers","depth":3},{"value":"Security Features","id":"security-features","depth":2}],"frontmatter":{"seo":{"title":"PERS Error Handling"}},"lastModified":"2026-07-24T12:04:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/8.error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}