{
  "code": "NOTIFICATION_EXPIRED",
  "message": "The notification deadline has passed and no longer accepts responses",
  "details": {
    "notification_id": "550e8400-e29b-41d4-a716-446655440000",
    "expired_at": "2025-05-25T11:00:00Z"
  },
  "request_id": "req_abc123def456"
}

function calculateRetryDelay(attempt) {
  // Start with 1000ms delay and double each time
  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 60000);
  
  // Add jitter (±10% of base delay)
  const jitter = baseDelay * 0.1 * (Math.random() * 2 - 1);
  
  return baseDelay + jitter;
}

{
  "code": "RESOURCE_LOCKED",
  "message": "Cannot apply changes because resource is currently locked by another operation",
  "user_message": "The system is currently processing another change. Please try again in a few moments.",
  "retriable": true
}

async function submitResponse(
  notification: Notification,
  actionId: string,
  responseData: any
): Promise<void> {
  const MAX_RETRIES = 3;
  let attempt = 0;
  
  while (attempt <= MAX_RETRIES) {
    try {
      const response = await fetch('/api/v1/client/respond', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${userToken}`
        },
        body: JSON.stringify({
          notification_id: notification.id,
          action_id: actionId,
          response_data: responseData
        })
      });
      
      if (response.ok) {
        return; // Success!
      }
      
      const errorData = await response.json();
      
      // Handle specific error cases
      switch (errorData.code) {
        case 'NOTIFICATION_EXPIRED':
        case 'NOTIFICATION_INVALIDATED':
        case 'NOTIFICATION_ALREADY_RESPONDED':
          // Terminal state, remove from UI
          removeNotification(notification.id);
          showUserMessage(errorData.message);
          return;
          
        case 'INVALID_RESPONSE_DATA':
        case 'CONSTRAINT_VIOLATION':
          // Validation error, show specific feedback
          showValidationError(errorData.details);
          return;
          
        case 'AUTH_EXPIRED_TOKEN':
          // Try to refresh the token
          await refreshUserToken();
          attempt++; // Don't count against retry limit
          continue;
          
        case 'RATE_LIMIT_EXCEEDED':
          // Get retry delay from headers
          const retryAfter = response.headers.get('Retry-After');
          const delayMs = retryAfter ? parseInt(retryAfter) * 1000 : calculateRetryDelay(attempt);
          await delay(delayMs);
          attempt++;
          continue;
      }
      
      // Server errors (5xx) are retryable
      if (response.status >= 500) {
        await delay(calculateRetryDelay(attempt));
        attempt++;
        continue;
      }
      
      // Other errors are considered permanent
      showUserMessage(`Error: ${errorData.message}`);
      return;
      
    } catch (error) {
      // Network errors are retryable
      if (error instanceof NetworkError) {
        await delay(calculateRetryDelay(attempt));
        attempt++;
        continue;
      }
      
      // Other exceptions are unexpected and should be logged
      logError('Unexpected error during response submission', error);
      showUserMessage('An unexpected error occurred. Please try again later.');
      return;
    }
  }
  
  // If we've exhausted retries
  showUserMessage('Unable to submit your response due to network issues. Please try again later.');
}

@app.route('/atp/webhook', methods=['POST'])
def handle_atp_webhook():
    # Verify webhook signature
    signature = request.headers.get('X-ATP-Signature')
    if not verify_signature(request.data, signature, webhook_secret):
        return jsonify({
            'code': 'INVALID_SIGNATURE',
            'message': 'Invalid webhook signature',
            'retriable': False
        }), 401
    
    data = request.json
    notification_id = data['notification_id']
    action_id = data['action_id']
    response_data = data.get('response_data')
    
    try:
        # Retrieve context for this notification
        context = get_notification_context(notification_id)
        if not context:
            return jsonify({
                'code': 'UNKNOWN_NOTIFICATION',
                'message': 'No context found for this notification',
                'retriable': False
            }), 404
        
        # Process the response based on action type
        if action_id == 'approve_deployment':
            try:
                result = process_deployment_approval(context, response_data)
                return jsonify({'status': 'success', 'result': result})
            except ResourceLockedException:
                return jsonify({
                    'code': 'RESOURCE_LOCKED',
                    'message': 'Deployment resource is currently locked',
                    'user_message': 'Another deployment is in progress. Please try again later.',
                    'retriable': True
                }), 409
        
        # Other action handlers...
        
    except TemporaryFailure as e:
        # Log the error with request ID for tracing
        logger.error(f"Temporary failure processing webhook: {str(e)}", 
                    extra={'request_id': request.headers.get('X-Request-ID')})
        
        # Return 503 to trigger retry with backoff
        return jsonify({
            'code': 'TEMPORARY_FAILURE',
            'message': str(e),
            'retriable': True
        }), 503
        
    except PermanentFailure as e:
        # Log the permanent error
        logger.error(f"Permanent failure processing webhook: {str(e)}",
                    extra={'request_id': request.headers.get('X-Request-ID')})
        
        # Return 422 to indicate the request was valid but couldn't be processed
        return jsonify({
            'code': e.code,
            'message': str(e),
            'user_message': e.user_message,
            'retriable': False
        }), 422
        
    except Exception as e:
        # Unexpected errors should be logged with full details
        logger.exception(f"Unexpected error processing webhook",
                       extra={'request_id': request.headers.get('X-Request-ID')})
        
        # Return 500 with minimal details to avoid leaking implementation details
        return jsonify({
            'code': 'INTERNAL_ERROR',
            'message': 'An unexpected error occurred',
            'retriable': True
        }), 500